how create api documentation postman
Aquest tutorial explica com es pot crear una documentació amb un bon estil i un esforç mínim mitjançant el suport de documentació de l'API proporcionat per Postman Tool:
Per a qualsevol API, ja sigui interna o pública, la documentació és un dels ingredients més essencials per al seu èxit.
El motiu principal d’això és que la documentació és la manera de comunicar-se amb els usuaris.
- Com s’ha d’utilitzar la vostra API?
- Què s'admeten tots els codis d'estat?
- Quins són els codis d'error?
- Quins tipus de mètode s’exposen?
Tota aquesta informació és necessària perquè tothom pugui utilitzar o implementar l'API per a la necessitat desitjada.
=> Mireu aquí les sèries de formació de carters senzills.
com declarar una matriu d'objectes a Java
Postman proporciona una metodologia de documentació fàcil d’utilitzar i, per a la documentació bàsica, és tan senzill com fer clic a un botó de la col·lecció Postman i podeu obtenir un URL públic per a la documentació de l’API.
Què aprendreu:
Creació de documentació API a Postman
Funcions de documentació
Les funcions més destacades del generador de documentació Postman inclouen:
- Admet la sintaxi de marcatge. Markdown és una sintaxi de documentació genèrica que normalment hauríeu d’haver notat en qualsevol projecte de Github. Permet que l'estil i el format de text siguin més familiars i fàcils.
- No hi ha requisits / sintaxis específics per crear documentació. La informació de sol·licitud i recopilació s’utilitza de la millor manera per generar documentació.
- Es pot publicar en un URL públic o en un domini personalitzat (per a usuaris empresarials).
- Genera fragments de codi per fer trucades a l'API en diferents idiomes com C #, PHP, Ruby, Python, Node, etc.
Creació de documentació
El generador de documents de Postman fa referència a la descripció de la col·lecció, la carpeta i la sol·licitud individual i les recopila mentre es crea o genera documentació per a la col·lecció.
Fa ús de diversos paràmetres de sol·licitud, com ara capçaleres, paràmetres de cadena de consulta, paràmetres de formulari, i indica l’ús d’aquests valors a la documentació de la sol·licitud.
Aquí teniu un vídeo tutorial:
Creem una col·lecció bàsica amb 3 sol·licituds amb la mateixa API de prova que els altres articles. Afegirem informació a la descripció de la col·lecció, així com a les sol·licituds individuals i també crearem alguns exemples de sol·licituds i respostes, que també es capturaran mentre es crea la documentació.
Seguiu els passos següents per afegir informació bàsica sobre les sol·licituds i després crear la documentació.
# 1) Creeu una col·lecció amb 3 sol·licituds, és a dir, Registre d’usuari, usuari d’inici de sessió i obtenció d’usuari (consulteu aquí per a sol·licituds de càrregues útils i URL d’API).
# 2) Ara afegim informació a la col·lecció en format de reducció. Markdown és un format estàndard que s’utilitza per a gairebé tota la documentació de Github (consulteu més informació sobre el markdown aquí ).
Afegirem una mica d’informació a la descripció de la col·lecció en el format de reducció, tal com es mostra a continuació.
Per previsualitzar l'aspecte de la reducció, consulteu el portal web de codi obert aquí.
# 3) Ara afegirem les descripcions a les sol·licituds individuals de la col·lecció. De manera similar a la col·lecció, també s’admet el format de reducció per a les descripcions de sol·licituds (per obtenir informació més detallada sobre la guia de reducció, consulteu aquí ).
Vegem una mostra d’una de les sol·licituds de registre de l’usuari final (el mateix es pot aplicar a altres sol·licituds).
Text de reducció:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status codeVisualització prèvia de reducció:
# 4) Per a tots els punts finals de l'API, capturem o desem un exemple que el generador de documentació utilitzaria.
Un exemple no és res més que un exemple de sol·licitud-resposta per a la sol·licitud de l'API. Si deseu la resposta com a exemple, el generador de documentació la pot capturar com a part de la documentació mateixa.
Per desar un exemple, premeu el botó 'Envia' per executar la sol·licitud i, a la pestanya de resposta, feu clic a Desa la resposta -> Desa com a exemple .
Un cop desat l'exemple, es manté a la col·lecció i es pot accedir en qualsevol moment en el futur mitjançant un Exemples enllaç al creador de sol·licituds.
# 5) Un cop s'hagi afegit tota la informació anterior, vegem com es crea una previsualització de la documentació.
Obriu les opcions de col·lecció i feu clic a ' Publica Documents '.
Nota: Una cosa important a tenir en compte aquí és que només els usuaris registrats amb Postman podran utilitzar la funció Publicar documents a Postman. El registre és gratuït, però s’ha de fer a través del vostre compte de correu electrònic. Hi ha altres funcions / funcions com compartir col·leccions i espais de treball, crear monitors, etc., que s'afegeixen als comptes registrats.
# 6) Un cop ' Publica Documents ”S’executa, s’obre una pestanya del navegador amb els detalls de la col·lecció Postman (internament Postman allotja aquesta col·lecció als seus propis servidors, a més del sistema de fitxers local de l’usuari).
Fer clic a 'Vista prèvia' per veure la documentació abans de publicar-la.
' Publica la col·lecció 'L'enllaç publicarà la documentació a un URL accessible públicament. En general, no es recomana publicar API que tinguin informació d’autorització confidencial per publicar a l’URL públic. Aquestes API es poden publicar mitjançant dominis personalitzats amb comptes empresarials de Postman.
# 7) Vegem com queda la previsualització de la documentació. Fent clic a ' Vista prèvia de la documentació 'Obre la documentació en un mode de previsualització allotjat als servidors de Postman. Vegem quins detalls diferents es capturen a la documentació (tal com hem configurat en diferents llocs. Per exemple , descripció de la col·lecció, descripció de la sol·licitud i exemples).
A les 2 captures de pantalla anteriors, podeu veure que tota la informació que es va afegir a la col·lecció i les descripcions de sol·licituds es captura de manera reduïda a la vista prèvia de la documentació.
preguntes i respostes d’entrevistes de garantia de qualitat per a estudiants de primer any
A més, la documentació de manera predeterminada proporciona enllaços d'idioma tal com es ressalta i això fa que sigui molt més fàcil per a algú que vulgui fer directament la sol·licitud de l'API en l'idioma llistat.
# 8) També us permet fer modificacions d’estil molt bàsiques, com canviar el color de fons, canviar el color de fons i de primer pla de les plantilles de capçalera, etc. detalls importants sobre l'API.
Conclusió
En aquest tutorial, hem recorregut el suport de documentació de l'API proporcionat per Postman, mitjançant el qual podem crear una documentació amb un bon aspecte i estil amb el mínim esforç.
També permet moltes bones plantilles i un estil definit per l'usuari que es podria aplicar als documents generats i també permet publicar documentació en un URL públic.
Per als punts finals de l'API privada, també hi ha una disposició per publicar documentació en un domini personalitzat que es pugui configurar per als comptes o usuaris de l'empresa.
Més lectura = >> Com es publica el Pact Contract to Pact Broker
=> Visiteu aquí per aprendre a Postman des de zero.
Lectura recomanada
- Tutorial POSTMAN: proves d'API mitjançant POSTMAN
- Com i quan s'utilitzen els scripts Post Request Pre i Post Request?
- Com s'utilitza Postman per provar diferents formats d'API?
- Com s'utilitza la integració de línia d'ordres amb Newman In Postman?
- Tutorial Rest API: Arquitectura i restriccions de l'API REST
- Genereu documentació vital amb escabetxos per als fitxers de funcions Specflow
- Automatització de la validació de respostes amb afirmacions a Postman
- Codis de resposta de l'API Rest i tipus de sol·licituds de descans