OpenAPI JSON objektumok, mint lekérdezési paraméterek

1. Áttekintés

Ebben az oktatóanyagban megtanuljuk, hogyan kell működni A JSON objektumok lekérdezési paraméterként az OpenAPI használatával.

2. Lekérdezési paraméterek az OpenAPI 2-ben

Az OpenAPI 2 nem támogatja az objektumokat lekérdezési paraméterként; csak a primitív értékek és a primitív tömbök támogatottak.

Emiatt inkább JSON paraméterünket akarjuk definiálni a-ként húr.

Ahhoz, hogy ezt működés közben lássuk, definiáljunk egy paramétert params mint a húr, annak ellenére, hogy háttérképünkben JSON néven elemezzük:

swagger: "2.0" ... elérési utak: / jegyek: get: címkék: - "jegyek" összefoglaló: "JSON objektum küldése lekérdezési paraméternek" paraméterek: - név: "params" itt: "útvonal" leírás: "{ \ "type \": \ "foo \", \ "color \": \ "green \"} "kötelező: true type:" string "

Így ahelyett, hogy:

GET // localhost: 8080 / api / jegyek? Type = foo & color = green

jól csinál:

GET // localhost: 8080 / api / tickets? Params = {"type": "foo", "color": "green"}

3. Lekérdezési paraméterek az OpenAPI 3-ban

Az OpenAPI 3 az objektumok támogatását vezeti be lekérdezési paraméterként.

A JSON paraméter megadásához hozzá kell adnunk a tartalom szakasz a definíciónkhoz, amely tartalmazza a MIME típust és sémát:

openapi: 3.0.1 ... elérési utak: / jegyek: get: címkék: - jegyek összefoglalása: JSON objektum küldése lekérdezés param paramétereként: - név: paraméterek: lekérdezés leírás: '{"type": "foo", "color": "green"} 'kötelező: true schema: type: object properties: type: type: "string" color: type: "string"

Kérésünk most úgy nézhet ki:

GET // localhost: 8080 / api / jegyek? Params [type] = foo¶ms [color] = zöld

És valójában még mindig így nézhet ki:

GET // localhost: 8080 / api / tickets? Params = {"type": "foo", "color": "green"}

Az első lehetőség lehetővé teszi számunkra a paraméter-ellenőrzések használatát, amelyek a kérés benyújtása előtt értesítenek bennünket, ha valami nincs rendben.

A második opcióval ezzel kereskedünk, hogy nagyobb legyen a háttérellenőrzés, valamint az OpenAPI 2 kompatibilitás.

4. URL kódolás

Fontos megjegyezni, hogy a kérésparaméterek JSON-objektumként történő továbbításakor dönteni kell a paraméter URL-kódolásáról a biztonságos szállítás érdekében.

Tehát a következő URL elküldéséhez:

GET / jegyek? Params = {"type": "foo", "color": "green"}

Valójában tennénk:

GET / jegyek? Paramek =% 7B% 22type% 22% 3A% 22foo% 22% 2C% 22color% 22% 3A% 22green% 22% 7D

5. Korlátozások

Tartsuk szem előtt a JSON objektum lekérdezési paraméterek halmazaként történő továbbításának korlátait is:

csökkentett biztonság
a paraméterek korlátozott hossza

Például, minél több adatot helyezünk el egy lekérdezési paraméterben, annál több jelenik meg a kiszolgáló naplóiban és annál nagyobb az érzékeny adatok expozíciójának lehetősége.

Ezenkívül egyetlen lekérdezési paraméter nem lehet hosszabb 2048 karakternél. Természetesen mindannyian el tudunk képzelni olyan forgatókönyveket, ahol a JSON-objektumaink ennél nagyobbak. Gyakorlatilag a JSON karakterláncunk URL-kódolása valójában körülbelül 1000 karakterre korlátoz minket a hasznos terhelésre.

Az egyik megoldás nagyobb JSON objektumok küldése a testbe. Ily módon kijavítjuk a biztonsági problémát és a JSON hosszkorlátozását is.

Tulajdonképpen, A GET vagy a POST egyaránt támogatja ezt. A GET-en keresztüli testküldés egyik oka az API RESTful szemantikájának fenntartása.

Természetesen ez egy kicsit szokatlan és nem általánosan támogatott. Például egyes JavaScript HTTP könyvtárak nem engedik meg, hogy a GET kérések kérelem törzset kapjanak.

Röviden, ez a választás kompromisszumot jelent a szemantika és az egyetemes kompatibilitás között.

6. Következtetés

Összefoglalva, ebben a cikkben megtanultuk, hogyan adhatunk meg JSON objektumokat lekérdezési paraméterként az OpenAPI használatával. Ezután megfigyeltük a háttérrendszer néhány következményét.

E példák teljes OpenAPI-definíciói a GitHub oldalon érhetők el.

streamalism.org