3 ms·

I agree with the argument: developers like reading web pages that describe how to use API, covering rationale of API design, gotchas, code samples. However, wh

by aslom 10y ago

I agree with the argument: developers like reading web pages that describe how to use API, covering rationale of API design, gotchas, code samples. However, what if the specs were able to capture what is in such human-readable pages (for example https://docs.cloudant.com/ https://docs.cloudant.com/)? What if API spec could be automatically derived out of HTML pages? Embed some metadata in HTML page and then we have both cake (human-readable) and eat it (machine-readable)?

frio 10y ago
That sounds very much like [API Blueprints](https://apiblueprint.org/ https://apiblueprint.org/), which [Apiary](https://apiary.io/ https://apiary.io/) back. I tried to get the organisation I work for to standardise on them (being able to run tests from a versioned API specification seemed like a fantastic way to hit two birds with one stone), but sadly, couldn't convince enough people.
- ewittern 10y ago
  What were the reasons people brought up against doing this?
  - frio 10y ago
    Mostly inertia. We're a large-ish company; I work in a remote office away from the majority of dev, and technical direction needs marketing. We ended up using Swagger, which doesn't solve as many of our problems (having documentation generated from code isn't as robust from a testing POV, particularly when your RESTful API is versioned), but my "perfect" is the enemy of the company's "good" :).
- seanp2k2 10y ago
  It also sounds like Swagger + OpenAPIs: https://openapis.org https://openapis.org
bbrennan 10y ago
I actually have two related projects here: Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger https://github.com/bobby-brennan/scrape-to-swagger Swagger to HTML docs: https://github.com/lucybot/lucy-console https://github.com/lucybot/lucy-console We also have a commercial version of the latter which you can see at any-api.com
- ewittern 10y ago
  Cool projects, thanks for pointing them out! So, the scrape-html-to Swagger one would basically allow you to keep Swagger up to date as you change the human-readable API documentation? In that case, someone still has to make sure the API documentation is in sync with the source code, right?
evv 10y ago
GraphQL accomplishes this pretty well. Graphiql is a brilliant example of human and machine readable API documentation.

by aslom 10y ago

frio 10y ago

That sounds very much like [API Blueprints](https://apiblueprint.org/ https://apiblueprint.org/), which [Apiary](https://apiary.io/ https://apiary.io/) back. I tried to get the organisation I work for to standardise on them (being able to run tests from a versioned API specification seemed like a fantastic way to hit two birds with one stone), but sadly, couldn't convince enough people.

ewittern 10y ago
What were the reasons people brought up against doing this?
- frio 10y ago
  Mostly inertia. We're a large-ish company; I work in a remote office away from the majority of dev, and technical direction needs marketing. We ended up using Swagger, which doesn't solve as many of our problems (having documentation generated from code isn't as robust from a testing POV, particularly when your RESTful API is versioned), but my "perfect" is the enemy of the company's "good" :).
seanp2k2 10y ago
It also sounds like Swagger + OpenAPIs: https://openapis.org https://openapis.org

bbrennan 10y ago

I actually have two related projects here: Scrape HTML to swagger: https://github.com/bobby-brennan/scrape-to-swagger https://github.com/bobby-brennan/scrape-to-swagger Swagger to HTML docs: https://github.com/lucybot/lucy-console https://github.com/lucybot/lucy-console We also have a commercial version of the latter which you can see at any-api.com

ewittern 10y ago
Cool projects, thanks for pointing them out! So, the scrape-html-to Swagger one would basically allow you to keep Swagger up to date as you change the human-readable API documentation? In that case, someone still has to make sure the API documentation is in sync with the source code, right?

evv 10y ago

GraphQL accomplishes this pretty well. Graphiql is a brilliant example of human and machine readable API documentation.