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?
Ratkaisu
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
Asiaan liittyvät artikkelit
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.