You might also look at https://github.com/tobilg/api2html
Sure. I'll check it out. I saw a similar product that would output OpenAPI to slate docs actually so that would be what I would lean towards just out of familiarity.
Ask HN: Is OpenAPI Documentation Superior?
11–19 of 19 posts
Re: Ask HN: Is OpenAPI Documentation Superior?
#12You can do both. Widdershins converts an OpenAPI definition to the markdown format used by Slatedocs. https://github.com/mermade/Widdershins
I saw this and I'm definitely leaning towards it now given what was said in this thread. Thanks!
Re: Ask HN: Is OpenAPI Documentation Superior?
#13I'd say the answer is no. People use OpenAPI because it produces a good result and fits conveniently into a company's workflow. The most important aspects of good API documentation are 1) correctness, 2) thoughtful and complete examples, and 3) a clear explanation of the data model and state transitions. These can be accomplished with any tool.
Fair enough. In regards to point number 3, do you believe that sandbox APIs that persist objects like what Stripe does a must-have or a nice-to-have or somewhere in between?
Re: Ask HN: Is OpenAPI Documentation Superior?
#14I've been looking at this (we have a lot of docs and our API docs are all written in asciidoc). I don't think the value of OpenAPI is in the documentation, though it seems pretty thorough. There are a lot of benefits for the API producer in terms of tooling and the ecosystem. But that tooling also helps the consumer. Look at all the tools listed here: https://openapi.tools/ Those that would be helpful to me as a cons…
as one of the maintainers of openapi.tools, thanks for the shout out! if we can do anything to make the little site better let me know and ill see about getting it done.
Thank you for all the work you're doing!
Re: Ask HN: Is OpenAPI Documentation Superior?
#15I'd say the answer is no. People use OpenAPI because it produces a good result and fits conveniently into a company's workflow. The most important aspects of good API documentation are 1) correctness, 2) thoughtful and complete examples, and 3) a clear explanation of the data model and state transitions. These can be accomplished with any tool.
Fair enough. In regards to point number 3, do you believe that sandbox APIs that persist objects like what Stripe does a must-have or a nice-to-have or somewhere in between?
For me it depends on what the API does, and how much testing costs.
If it's something like Stripe (payments), Plaid (collects bank credentials), or Lob (sends physical mail), you definitely need a sandbox beyond the MVP stage. At one point we had a pre-launch payments API at Square and we provided partners with prepaid debit cards to test with, but that approach obviously doesn't scale well.
Another huge benefit of sandbox APIs is that people can use them for CI when testing their own integrations.
Still, when the cost of creating and manipulating objects in the production API is negligible I would say a sandbox is unnecessary.
As for how much persistence is needed in the sandbox, start with what is easiest to implement and gather feedback from your developers.
Be aware that developers often throw out ideas of API features that would be nice to have without much though about priority of effort involved. Sometimes they ask for something and then don't get around to updating their integration to take advantage of it.
Re: Ask HN: Is OpenAPI Documentation Superior?
#16> Outside of the autogenerating aspects, are there benefits for the API consumer? Mostly familiarity. The OpenAPI spec and the Swagger tools are something that a _lot_ of devs are familiar with, and they integrate well with lots of other tools (We have OpenAPI docs embedded in out Confluence/Jira workflow). That SlateDocs looks nice, but I've never heard of it before. If I had two browser tabs open to evaluate differ…
So there is an intuitive aspect that brings comfort? I think that's super important. Especially in healthcare where most APIs/dev experience is terrible, making someone feel at home seems really important.
Not so much “intuitive“, much closer to “familiar”. I don’t expect an API doc tool (or any useful/powerful dev tool) to be zero learning curve, but I don’t want my team climbing 2 or 3 different learning curves unnecessarily.
But yeah, totally right on the “feeling at home” idea.
Re: Ask HN: Is OpenAPI Documentation Superior?
#17You can do both. Widdershins converts an OpenAPI definition to the markdown format used by Slatedocs. https://github.com/mermade/Widdershins
Oooh, nice. That looks potentially useful.
For people who haven’t clicked the link, this assumes you’re defining your API in OpenAPI/Swagger/a few other options, and (one directionally) converts it to suitable formats for static publishing:
Widdershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a renderer, such as Slate, ReSlate, Shins (deprecated) or html suitable for use with ReSpec.
Re: Ask HN: Is OpenAPI Documentation Superior?
#18You can do both. Widdershins converts an OpenAPI definition to the markdown format used by Slatedocs. https://github.com/mermade/Widdershins
Widdershins works pretty well. IIRC their README also links to a CLI tool that wraps Widdershins.
I containerized it and added some wrapper scripts so we can just drop the YAML spec in our repo and have build automation to generate/deploy a web site with all the relevant docs.
Re: Ask HN: Is OpenAPI Documentation Superior?
#19Earlier quoted context omitted.
Fair enough. In regards to point number 3, do you believe that sandbox APIs that persist objects like what Stripe does a must-have or a nice-to-have or somewhere in between?
For me it depends on what the API does, and how much testing costs. If it's something like Stripe (payments), Plaid (collects bank credentials), or Lob (sends physical mail), you definitely need a sandbox beyond the MVP stage. At one point we had a pre-launch payments API at Square and we provided partners with prepaid debit cards to test with, but that approach obviously doesn't scale well. Another huge benefit of s…
ya that's a fair point. Right now we just give canned responses but our API does have real world implications like Lob. Actual test kits get sent out. It's hard to balance essentially duplicating your prod environment for the sake of simulating things vs canned responses which just give you the different responses you'd expect. I guess the big downside is you don't get to test asynchronous changes to objects.