Jagshemas,
v tomto insighteri by som vam chcel predstavit generovanie API dokumentacie pre webove aplikacie.
O co ide?
Dokumentavanie webovych endpointov je velmi dolezite pokial chcete, aby vase API pouzivali aj ostatni ludia.
Nikto poriadne neriesi ako vlastne na to a vela krat je vysledkom iba odflaktnuty automaticky vygenerovany swagger napr. z .NETu.
Ako bude vygenerovana dokumentacia vyzerat/o co sa vlastne jedna vizualne?
Priblizne takto: https://stripe.com/docs/api/orders/object a takto https://redocly.github.io/redoc/#section/Introduction
Ako nato?
Existuje super standard, ktory sa vola OpenAPI (ako inak). Je to schema JSON/YAML suboru v ktorom popisujete vase API.
Zaklad suboru vam dokaze pravdepodobne vyexportovat vas framework, ako napr. vyssie spominany Swagger v .NET.
Na editovanie a pridavania examplov, popisu a pod. je opensource SW s nazvom Spotlight Studio.
A finalne, na generovanie sa moze pouzit redoc, ktory vam dokaze subory bud servovat (ako http server) alebo vygeneruje standalone all-in-one html subor, ktory si nahodite na svoj web.
Pre generovanie sa pouzije jednoduchy prikaz:
npx redoc-cli bundle <nazov_suboru.yaml>
(nodeJs potrebne. npx spusti npm package bez toho, aby ho stiahol).
Linky:
Spotlight Studio - https://stoplight.io/studio/
ReDoc - https://github.com/Redocly/redoc
OpenAPI specka - https://www.openapis.org/