La prima vedere la swagger nu imi place ideea ca toata documentatia este intr-o singura pagina rendata. Pentru API cu multe module si operatii as avea nevoie ca ele sa fie separate. Probabil ar trebui generat un fisier pentru fiecare modul in parte.
Intr-un proiect pe care l-am preluat am gasit http://raml.org
Nu e neaparat rau, mie mi-a placut swagger cand l-am folosit, dar nici n-am schimbat mare branza in raml pe noul proiect cat sa ma pronunt. Am citit in schimb lucruri bune despre el cand am vrut sa vad “ce e”
Swagger e ditamai tech debt și nu e (adică sunt diferențe minime cu postman + ceva scris în orice fel de documentație la timpul salvat), emag își permite să arunce un pdf făcut în 10 minute prin word, platformele de plăți prin cardul la fel, băncile la fel și nouă ne trebuie fainoșaguri gen swagger.
Folosesc doar Postman/curl + ceva fișier text în sublime text cu scheme ascii și niciodată n-aș trece pe o platformă, am alte lucruri de făcut, e pur și simplu inutil dacă n-ai ceva proiect super fain la care vrei ca toți să fie invidioși pe tine că ai documentație cu design, exemple și playground. (eu n-am ajuns înca la acest nivel cu nici un proiect, clienții mei nici nu știu ce e ăla API, nu să le trebuiească așa ceva)
Totuși RAML îmi pare simpatic, dar când văd că ar trebui să învâț să lucrez cu el și să combin ce fac pe hârtie cu RAML nu l-aș prea folosi.
Nu am inteles prea bine de ce acesta e un argument pozitiv. Din putinele mele interactiuni cu oameni care au lucrat acolo, am ramas doar cu horror stories (tehnice). Va rog sa ma contraziceti, nu-s incuiata sa raman pe ideea negativa pe care mi-am creat-o.
Eu am folosit acum cativa ani Guzzle service descriptions de musai, si am ramas foarte placut impresionata de cresterea in productivitate. Le foloseam si ca documentatie. Erau minunate. Dar Guzzle a luat-o razna cu multe major releases care sparg compatibilitatea si am lasat-o mai moale cu utilizarea tuturor features-urilor sale.
Din punctul meu de vedere, swagger face ceva extrem de asemanator cu service descriptions mentionate un pic mai sus, doar ca nu-ti da si clientul.
The Open API Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described.
Ce au deaface standardele cu un framework pentru a realiza, testa, documenta, interacționa cu api-uri pe care trebuie să îl înveți pe lângă orice standard sau recomandare și care îți face mai mulți nervi decât te ajută dacă lucrezi singur ? (aka un orm care pare frumos la început și după îți dai seama că e chineză)
Sigur se merită la proiecte mari, faine. Dar dacă mie îmi trebuie un api pentru un frontend react SIGUR nu stau toată ziua să învâț și ceva tool pe lângă când abia aștept să văd ceva din baza de date în vreo componentă cu alte 50 de componente.
Ori swagger, ori RAML ai documentație tehnică de 100 de pagini. Dacă știu deja JS, curl, regex, de ce să nu folosesc pur și simplu JS să fac tot ce pot face aceste framework-uri, fără să mai stau să învâț liturghii de DSL. API playground faci cu express în 30 de secunde dacă nu îți place postman. Dacă nu folosești tool-uri de genul ții api-urile tale cât mai simple posibil și nu trebuie documentații în care explici 50 de coduri de răspuns/GET. Eventual te enervezi și nici nu mai folosești rest ci MQ sau pub/sub, ceva hibrid cu rpc.
Cu emag vroiam să zic că pe ei nici nu îi interesează și învârt zilnic câteva milioane de euro cu acele API-uri, de ce mi-ar păsa mie să îmi adaug înca un punct de fatigue când nu învărt nici 5 lei cu api-urile mele.
Whut?