search

okffi / open-api-definition

Community governed definition of open API
http://okffi.github.io/open-api-definition/
Creative Commons Zero v1.0 Universal
7 stars 7 forks source link

Avoimen rajapinnan dokumentaatio määritelmässä #33

Open Mygee opened 8 years ago

Mygee commented 8 years ago

Avaan nyt keskustelun määritelmän vaatimasta avoimen rajapinnan dokumentaatiosta. Yleisesti dokumentaation puute on suurin este rajapintojen hyödyntämiseen. Esimerkiksi koodiesimerkkien puute on todellinen ongelma rajapinnan hyödyntämisessä.

aapris commented 8 years ago

Olen samaa mieltä ja jokaisesta rajapinnasta pitäisi olla vähintään komentoriviesimerkkejä (esim. curl- tai httpie-ohjelmalla tai vastaavalla) sekä ainakin 1-2 eri ohjelmointikielellä (esim. java, html+javascript, node.js, python) tehdyt esimerkit, joilla dataa saa pyydettyä rajapinnasta ja käsiteltyä sitä jollain tavoin. Aina parempi, jos rajapinnan tarjoajalla olisi tarjota myös jonkinlainen SDK (softamoduuli/kirjasto), jolla pääsee helposti ja nopeasti käyttämään rajapintaa.