Noi scriem documentația api cu raml

  • 24.08.15 11:51 •
  • yuhenobi •
  • # 265337 •
  • Habrahabr •
  • 37 •
  • 8709

- la fel ca Forbes, doar mai bine.

Comoditatea de a lucra cu orice API în multe feluri depinde de modul în care documentația sa este scrisă și încadrată. Acum lucrăm la standardizarea și unificarea descrierii tuturor API-urilor noastre, iar problemele legate de documentare sunt deosebit de relevante pentru noi.






După o căutare lungă, am decis să elaborăm documentația în format RAML. Acesta este numele unei limbi specializate pentru descrierea API-ului REST. Despre capabilitățile și beneficiile sale, vom discuta în acest articol.

De ce RAML


Cum se documentează API-ul? Această întrebare nu este la fel de simplă cum ar părea la prima vedere.
Prima și cea mai simplă opțiune care vine în minte este să furnizeze o descriere a API sub forma unui document de text simplu. Deci, face atât de multe (inclusiv companii foarte bine-cunoscute). De asemenea, am folosit această metodă de mai multe ori. Pentru simplitatea sa, are următoarele dezavantaje:

  • este dificil să actualizați documentele text;
  • deseori descrierile verbale ale API nu sunt suficient de clare;
  • Domeniul de utilizare a documentației "verbale" este foarte limitat (de exemplu, pe baza ei este imposibil să se genereze o pagină de test interactivă).

Pentru a simplifica procesul de documentare, puteți utiliza instrumente și servicii specializate. De obicei, ele generează documentația bazată pe descriere într-un format standardizat - de obicei JSON sau Markdown.

Niciunul dintre aceste formate nu este potrivit pentru scrierea de documente. JSON a fost creat inițial pentru schimbul de date pe web. Când îl folosiți în alte scopuri, trebuie să recurgeți la ajutorul "cârligelor" - de exemplu, câmpurile personalizate începând cu semnul $. În plus, crearea de manuale în format JSON este destul de rutină și obositoare (mai ales când vine vorba de descrieri de dimensiuni mari).

Desigur, YAML este mult mai convenabil decât JSON. Dar utilizarea lui implică anumite dificultăți. Faptul este că descrierile API conțin întotdeauna elemente duplicate (de exemplu, o schemă de răspuns care poate fi aceeași pentru diferite tipuri de cereri HTTP) pe care trebuie să le scrieți manual de fiecare dată. Acum, dacă ați putea o dată pentru totdeauna să le înregistrați într-un dosar separat și să vă referiți la acesta în caz de necesitate ... Dar, din păcate, încă nu există o astfel de posibilitate.

Avantajele indiscutabile ale RAML sunt:
  • sintaxă simplă și logică bazată pe formatul YAML;
  • suport pentru moștenire și capacitatea de a conecta fișiere de specificații externe.

Un avantaj suplimentar este disponibilitatea unui număr mare de convertoare, parser și generatoare de documentație online. Vom discuta câteva dintre ele mai jos, dar pentru moment, să trecem la o revizuire a caracteristicilor sintaxei RAML.

O scurtă introducere la RAML

Structura documentului


Fișierul de specificații pe RAML constă din următoarele elemente structurale:

  • partea introductivă ("cap");
  • schema de securitate;
  • descrierea profilurilor;
  • descrierea obiectelor și metodelor;
  • descrierea răspunsurilor.

Să luăm în considerare aceste elemente în detaliu.

prodrom


Fiecare document de pe RAML începe cu o parte introductivă care include patru elemente necesare:

  • Versiunea RAML;
  • numele documentului;
  • URI pentru care API este disponibil;
  • Versiunea API descrisă în documentație.

Se pare ca aceasta:


Partea introductivă poate include, de asemenea, diverse informații suplimentare - de exemplu, informații despre protocolul utilizat pentru a comunica cu API:


De asemenea, puteți scrie metadatele fișierului de documentare în introducere:

Diagrame de securitate

Fragmentul următor conține următoarele informații:


Acest lucru ajută la accelerarea procesului de documentare, la evitarea repetițiilor inutile și la diminuarea volumului de documentație.

Citiți mai multe despre schemele de securitate și vedeți aici exemple specifice (secțiunea Securitate).







Obiecte și metode


Următoarele sunt obiectele principale și căile spre ele, precum și metodele HTTP care sunt utilizate cu aceste obiecte:


În exemplul de mai sus, este descris un API, cu care puteți lucra cu documente. Putem descărca documente pe mașina locală (GET), schimbați documentele existente (PUT) și încărcați altele noi (POST). Cu fiecare document individual (), putem efectua, de asemenea, următoarele operații: descărcați pe mașina locală (GET) și ștergeți (DELETE).
Antetele HTTP utilizate cu această sau acea metodă sunt descrise folosind proprietatea anteturilor, de exemplu:


Notați proprietatea cerută: indică dacă este necesar antetul (adevărat) sau opțional (false).
În descrierea obiectelor și a metodelor, pot fi utilizați numeroși parametri suplimentari. Luați în considerare următorul exemplu:


Aici indicăm faptul că fiecare dintre documentele accesate prin API are propriul cod de identificare ca și șir (tip: șir) și descriem formatul acestui cod folosind expresii regulate.

Proprietățile descrierii, tipului și modelului pot fi de asemenea utilizate în descrierile metodelor, de exemplu:

Pentru fiecare metodă, puteți scrie o schemă individuală de securitate:

Parametri de interogare


Pentru fiecare metodă din documentație, puteți specifica parametrii de interogare care vor fi utilizați în interogare. Pentru fiecare parametru de interogare sunt specificate următoarele caracteristici: nume, tip, descriere și exemplu:


Pentru a evita repetarea inutilă în descrieri, RAML folosește trăsături care sunt prescrise în partea introductivă a documentului:


În viitor, profilul poate fi accesat prin descrierea oricăror metode:


Mai multe detalii despre profilurile și caracteristicile utilizării lor pot fi găsite în documentația oficială (secțiunea Trasaturi).

Descrierea răspunsului


Descrierea răspunsului trebuie să indice codul său. De asemenea, în descriere, puteți adăuga o schemă (schemă) - o enumerare a parametrilor care intră în răspuns și tipurile acestora. De asemenea, puteți da un exemplu de răspuns specific (exemplu).


Schemele de răspuns pot fi salvate în fișiere separate .yml sau .raml și se pot consulta în alte părți ale documentației:

Vizualizarea și generarea de documente

RAML2HTML și alte convertoare


În ciuda faptului că RAML este un format relativ nou, au fost deja dezvoltate suficiente convertoare și parseruri. Un exemplu este ram2htmtl. generând o pagină HTML statică bazată pe descrierea RAML.
Se instalează utilizând managerul de pachete npm:


Pentru a converti un fișier RAML în HTML, executați pur și simplu o comandă simplă:

API Designer

În partea dreaptă a paginii, se generează automat o documentație interactivă. Aici puteți testa și API-ul: pentru a face acest lucru, extindeți pur și simplu descrierea interogării și faceți clic pe butonul Încercați.

API Designer vă permite, de asemenea, încărcarea fișierelor RAML de la mașina locală. Acesta acceptă importul de fișiere descriptive API pentru Swagger.
În plus, API-ul Designer stochează statistici de interogări de testare în raport cu API-ul.

Consola API


Consola API este un instrument util, dezvoltat de aceeași companie MuleSoft. Folosindu-l, puteți genera documentația către API direct în browser. Fișierele de specificații pot fi descărcate de pe aparatul local sau puteți specifica o legătură către o sursă externă:

Noi scriem documentația api cu raml

Consola API include mai multe fișiere exemplu, care sunt descrieri ale API-ului pentru serviciile web populare: Twitter, Instagram, Box.Com, LinkedIn. Am încercat să generăm documentația bazată pe unul dintre cele mai de jos - arată destul de frumos:

Noi scriem documentația api cu raml

Documentația primită la ieșire este interactivă: în ea nu puteți doar să citiți descrierea API, ci și să efectuați interogări de testare.

concluzie

Numai utilizatorii înregistrați pot participa la sondaj. Conectați-vă. te rog.

Cu atât mai bine? Răspund la puncte?

1. O sintaxă mult mai simplă și logică a descrierilor.
2. Posibilitatea de a scrie un număr mult mai mare de parametri în documentație decât în ​​aceeași lucrare și, cel mai important, o faceți cu construcții mai simple și mai convenabile (comparați aceleași descrieri ale schemelor de securitate sau ale parametrilor de interogare).
3. Extinderea (în comparație cu același bâzâit) utilizarea include și moștenirea, astfel încât documentația să fie mai compactă și mai elegantă.

Singurul lucru pe care RAML îl pierde în prezent pentru Swagger este numărul inadecvat de instrumente dezvoltate de comunitate. Dar aceasta este o afacere lucrativă.

Pentru RAML, există instrumente care generează automat documentația în acest format pentru un API existent (de preferință în zbor)?

Folosesc în mod activ modelul de format, tot ceea ce este descris în articol pentru RAML este în bluetooth. Rezultatul este un frumos și ușor de utilizat, dar pentru un pic de format model scriitor api koryavenko, foarte inconfortabil, de exemplu, urmați Chur cerințe stricte cu privire la numărul de spații și file: lista de parametri - aceasta înseamnă două Taba, altceva - patru Taba, etc. .D. Se pare un pic inutil, pentru ca este evident sa parsezi si totul se va intampla.

La noi în PHP, API-ul proiectului este descris pe WSDL, această descriere funcționează și pentru validarea primară. Documentația este obținută utilizând transformarea XSLT WSDL-ki. Abordarea sa dovedit a fi bună. Dar setul de instrumente descrise în articol în jurul RAML este impresionant.







Articole similare

Trimiteți-le prietenilor: