Objekty OpenAPI JSON ako parametre dotazu

1. Prehľad

V tomto výučbe sa naučíme pracovať s Objekty JSON ako parametre dotazu pomocou OpenAPI.

2. Parametre dotazu v OpenAPI 2

OpenAPI 2 nepodporuje objekty ako parametre dotazu; podporované sú iba primitívne hodnoty a polia primitívnych prvkov.

Z tohto dôvodu budeme namiesto toho chcieť definovať náš parameter JSON ako a struna.

Aby sme to videli v akcii, definujme parameter s názvom params ako povrázok, aj keď to v našom backende rozoberieme ako JSON:

swagger: "2.0" ... cesty: / vstupenky: get: tagy: - "vstupenky" zhrnutie: "Poslať objekt JSON ako dopyt param" parametre: - názov: "params" v: "cesta" popis: "{ \ "type \": \ "foo \", \ "color \": \ "zelená \"} "povinný údaj: pravý typ:" reťazec "

Teda namiesto:

ZÍSKAŤ // localhost: 8080 / api / vstupenky? Type = foo & color = green

urobíme:

ZÍSKAŤ // localhost: 8080 / api / vstupenky? Params = {"type": "foo", "color": "green"}

3. Dotaz na parametre v OpenAPI 3

OpenAPI 3 zavádza podporu pre objekty ako parametre dotazu.

Ak chcete určiť parameter JSON, musíme pridať a obsah časť našej definície, ktorá obsahuje typ a schému MIME:

openapi: 3.0.1 ... cesty: / vstupenky: get: tagy: - prehľad vstupeniek: odoslanie objektu JSON ako dotazu parametre parametre: - názov: parametre v: popis dotazu: '{"type": "foo", "color": "green"} 'vyžadované: true schéma: type: vlastnosti objektu: type: type: "string" color: type: "string"

Naša požiadavka môže teraz vyzerať takto:

ZÍSKAŤ // localhost: 8080 / api / vstupenky? Parametre [typ] = foo¶ms [farba] = zelená

A v skutočnosti to môže stále vyzerať takto:

ZÍSKAŤ // localhost: 8080 / api / vstupenky? Params = {"type": "foo", "color": "green"}

Prvá možnosť nám umožňuje používať validácie parametrov, ktoré nás pred odoslaním žiadosti informujú, či niečo nie je v poriadku.

S druhou možnosťou to obchodujeme pre väčšiu kontrolu nad backendom, ako aj pre kompatibilitu OpenAPI 2.

4. Kódovanie URL

Je dôležité si uvedomiť, že pri tomto rozhodovaní o prenose parametrov požiadavky ako objektu JSON budeme chcieť kódovať URL, aby sme zaistili bezpečný prenos.

Takže na odoslanie nasledujúcej adresy URL:

ZÍSKAŤ / lístky? Params = {"type": "foo", "color": "green"}

Vlastne by sme robili:

ZÍSKAŤ / letenky? Parametre =% 7B% 22typ% 22% 3A% 22foo% 22% 2C% 22color% 22% 3A% 22zelená% 22% 7D

5. Obmedzenia

Pamätajme tiež na obmedzenia týkajúce sa odovzdávania objektu JSON ako množiny parametrov dotazu:

znížená bezpečnosť
obmedzená dĺžka parametrov

Napríklad, čím viac údajov umiestnime do parametra dotazu, čím viac sa zobrazí v protokoloch servera a tým vyšší je potenciál vystavenia citlivým údajom.

Jeden parameter dopytu tiež nemôže mať viac ako 2 048 znakov. Určite si všetci dokážeme predstaviť scenáre, keď sú naše objekty JSON väčšie ako to. Prakticky povedané, kódovanie URL nášho reťazca JSON nás v skutočnosti obmedzí na asi 1 000 znakov pre naše užitočné zaťaženie.

Jedným z riešení je poslať väčšie objekty JSON do tela. Týmto spôsobom opravíme problém so zabezpečením aj obmedzenie dĺžky JSON.

Vlastne, Podporuje to GET alebo POST. Jedným z dôvodov, prečo poslať telo cez GET, je zachovať sémantiku RESTful nášho API.

Je to samozrejme trochu neobvyklé a nie všeobecne podporované. Napríklad niektoré knižnice HTTP JavaScriptu neumožňujú požiadavkám GET mať telo žiadosti.

Stručne povedané, táto voľba predstavuje kompromis medzi sémantikou a univerzálnou kompatibilitou.

6. Záver

Ak to zhrnieme, v tomto článku sme sa naučili, ako špecifikovať objekty JSON ako parametre dotazu pomocou OpenAPI. Potom sme pozorovali niektoré dôsledky na backend.

Kompletné definície OpenAPI pre tieto príklady sú k dispozícii na GitHub.

streamalism.org