Mitkä ovat Swagger/OpenAPI kuvauksen vähimmäisvaatimukset, jotta API:n voi julkaista?

Last modified by Xwiki VePa on 2024/02/07 07:37

Ongelma

Haluan julkaista API:n, mutta en tiedä mitä siltä vaaditaan. Mikä on Swagger/OpenAPI kuvauksen vähimmäisvaatimus, jotta API on julkaisukelpoinen?

Rajapinnan kuvaukselta edellytetään OpenAPI (Swagger) -standardin mukainen kuvaus, joka sisältää:

palvelun nimi ja kuvaus (mitä palvelu tekee)
palvelun teknisen ylläpidon yhteysosoite
rajapinnan kutsuosoitteet kuten /organisation/financial sekä niiden tarkat kuvaukset
kutsuesimerkit tarkalla tasolla: Onko GET/POST/muu, json vai muu, mahdolliset annettavat lisäparametrit, pakolliset kentät
sanomamuodot: application/json, text/xml, palautettavan tai lähetettävän objektin tarkka kuvaus kenttien tyyppeineen sekä rajoitteineen(maksimi pituus)
tunnistautuminen: vaaditaanko esimerkiksi api-avain joillekin metodeille/koko APIlle
virheilmoituksien kuvaukset: esimerkiksi 404 = ei löydy
lisenssiehdot, jos on

Aiheeseen liittyvät artikkelit näytetään tässä valittuihin leimoihin pohjautuen. Klikkaa makroa muokataksesi sitä, jos haluat muuttaa leimoja.

Unknown macro: contentbylabel. Click on this message for details.

Unknown macro: details. Click on this message for details.