given ever-increasing demand , desire create rest-based apis, supporting resources create , support loosely rest-based api? i'm looking tools, standards, processes, or tips else in industry uses documenting , maintaining rest api endpoints, both (in-code / maintenance), , clients may consume api (external-facing api docs).
brief backstory: i've been programming apis 10+ years in form or another, mobile since dawn of smartphone. have authored of own scratch , typically use rpc-based protocols because easy automatically generate documentation via docblocks.
in last few years have been contracted out support clients apis, , when jump in, regardless of language, follow absolutely no standard (code styling , api implementation) , have absolutely no documentation, neither in code, nor in how consume api. causes client-developers have have competence , access front-end , backend code figure out how consume web services, in addition wasting lot of time. arrive yet organization programmers have decided go rest route i'm seeing problem yet again i'm leaning on community see others do.
it's been experience rest-based apis nice consume when constructed , have wonderful documentation, difficult document , maintain. have separately maintain , engineer documentation api , can't leverage docblock parsing engines. every time have problem google around, , lately have stumbled onto...
which won't work rest apis i've worked on because of non-standard implementation of rest including custom headers, api keys, object definition formats, etc.
and toolkit/format i've come across raml...
which looks promising, requires separate code documentation of api. and, well, seems that's format/toolkit around support i'm looking seems rather new , doesn't in-line documentation. , trying ask programmers learn new file format , write raml in addition code pulling teeth.
so, tools, processes, etc. , teams use?
in past i've used wadl-to-html tools one. it's tricky, , must have wadl of services (if using java's jersey wadl can generated automatically), result not bad @ all. advantage of tool 1 don't have mantain documentation since automatically generated. disadvantage is similar javadoc, i.e. doesn't give 'the big picture' of api, details.
Comments
Post a Comment