Jump to content

návod [INSIGHTER™] API Dokumentacia 🦾


Deleted User

Recommended Posts

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/

Edited by Jiu
  • Líbí se mi to! (+1) 2
Link to comment
Share on other sites

  • 1 year later...
  • Administrátor

Určitě je to nice pro velky projekty. Já jsem pro to aby si to člověk psal sám a ať už pomocí oapi protože tím jak to píšeš sám najdeš hromadu píčovin který si navrhl na hovno akorát ti to doty doby než jsi zo musel zavolat a zdokumentovat response nepřišlo.  Kazdopadne určitě kdyz mas projekt ktery treba prebiras a neni k nemu zadny info tak je to lepší než nic

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...