What API documentation generator / tool are you folks using?
Hard requirement for me is version-able documentation - you can change versions on th...
For further actions, you may consider blocking this person and/or reporting abuse
Just yesterday I have setup Postman workspace for my api and it generated a pretty docs. Workspace supports collections just name your collection of requests as v1, v2 etc and you will get documentation for each “version”
I'm a big fan of having a Postman collection of your API endpoints, for your QA or pentesting teams. I didn't know they generated documentation, I will look into that. Also a good opportunity to compare to Postwoman.
I liked Slate but have also toyed around with Stoplight.io a bit. Worth having a look.
You can generate some fairly decent API docs with Postman too. You can't do a huge amount of customisation currently but this looks like it's a mid-term goal on their roadmap: trello.com/b/4N7PnHAz/postman-road...
Stoplight.io looks pretty interesting. Will check it out, thanks.
Full discloser - I work for Stoplight. I'm typically a docs consumer, not creator, so I don't have any real preference for how they're generated. All the same, as an employee I'm biased.
We've got 2 different docs options, this one is free & basic stoplight.io/docs/
If you need more theming options, this one is paid but there is a free trial stoplight.io/hubs/. Big Commerce uses this plan and they've made some pretty slick lookin' docs if I do say so myself. developer.bigcommerce.com/
I like the idea of the files changed red/green view, if that isn't a capability we already have, I'm going to add it to our roadmap (anyone can add & vote for roadmap items, it's found at stoplight.io/p/roadmap.)
Update We do have versioning capabilities on our docs hubs product stoplight.io/hubs/ docs.stoplight.io/platform/version...
thanks for the comment, I liked what bigcommerce did with stoplight.io but I wanted to try it in stoplight.io/hubs/ but I couldn't I think you are still working on it
Yeah, the version that BigCommerce started using a few years back is considered legacy now, we're rolling out the latest and greatest in mid-April. In the meantime, you can still write basic docs with stoplight.io/docs/ and the April release will include a bunch of neat features.
We use Redoc here at DEV, it generates from OpenAPI 3
I agree with you, that page is really troublesome, but we don't generate the API from the spec and we don't plan to. It's just used as a specification format.
Yeah OpenAPI is great for its ubiquity and cross-tool support, I have to admit. I like how Redoc organizes the content and its UI is clean.
I've been working on an open source tool that's kind of like Git but for APIs. It that automatically writes and maintains your API spec to save time and ensure its accuracy useoptic.com
This looks really neat.
You could try FastAPI: github.com/tiangolo/fastapi
You write your code in Python, using standard Python type declarations, and it generates OpenAPI for you, including Swagger UI and ReDoc.
I see you don't want OpenAPI, but it might be worth checking as it can help you simplify things. It also has OAuth2 integrations that can facilitate security.
Disclaimer: I'm the author 🤷
I use ApiDoc for my NodeJS - Express API, Generate an index.html with a little function, a simple npm to install, they have a good doc.
You just need to implement some commentary and Voila, you have your doc !
Ah, apiDoc is what I remember using a few years ago. I was really happy with it. Definitely going to compare it to some other options. It's got the versioning and just looks a little cleaner than readthedocs, which is nice.
Can you set up example requests with apiDoc? A quick look over its documentation doesn't seem to highlight this as a feature. So beyond documenting the API call in comments over the function, including an example request with request parameters filled out with some test data.
Sure, you to give you an idea, you have an "template" block i use and replace to edit my parameter, result and error :
And it give you that
thepracticaldev.s3.amazonaws.com/i...
I'm using app.restcase.com
It's a great online utility for maintaining your API specifications.
It allows project level management of APIs, generate nice shareable UI specification for the APIs, and even provide tests infrastructure for the It's based on OpenAPI v2 and v3 so it's easy to migrate to it.
I'm using this tool to sync between QA and development department
Hyde and Jekyll.
C++ documentation tool Hyde. Clang based using libTooling library. Produces structured markdown files, with YAML front-matter. And helps maintain the API documentation by mashing C++ changes with the documentation, so the documentation stays in sync with the evolving code.
Jekyll transforms markdown to static HTML, which can then be easily pushed en masse to your internal (intranet) or external (internet) webserver.
Hey! Founder of ReadMe here! We do have a ton of examples (try clicking any of the logos), and you don't need to contact us to sign up... there's a signup link and a completely free trial with all the features enabled!
I didn't know the company logos were clickable. Those are great examples. Thanks!
we use this github.com/apidoc/apidoc
apiDoc is the generator I couldn't recall the name of! I really enjoyed using this in the past.
I used SpringRestDocs (spring.io/projects/spring-restdocs) plus Asciidoctor and couldn't be more happy
You can write your documentation manually and include snippets generated from your test. You can assert the test to align the request/response with the documentation and fail if some of them is not what the documentation expects
I haven't personally used it. But I have seen a lot of people use it.
github.com/slatedocs/slate
I like that this is markdown-based, although having to document the API separately from the code creating the API endpoints could lead to unintentional drift. I'm going to keep this one in mind.
If you're still looking, how about Scribe (I'm the maintainer)? It tries to extract the docs from your code with as little config as possible, and it can automatically call your endpoints to generate sample responses. We've got versions for Laravel and popular Node frameworks.
I have started using npmjs.com/package/swagger-jsdoc
I;m using ascii doc. You can generate doc during compile time, so there is a way to paste some code or http requests from tests
Asciidoc I'm really not excited about. You have to write out verbose stuff separate from your code and, in my opinion, it doesn't end up reading very easily. For API documentation - there are other documentation needs that asciidoc services. What are the reasons you use asciidoc?
I'm using Swagger UI to auto-generate API from Rest Controller, when we start API, we have Documentation :D...but It's so bad :( And I'm trying to change to another better than
I'm not in the loop about the details of their deployment, but yes, they are still using Stoplight. I'm not quite sure what you mean by new version.
Redoc is also great for documentation.
I'm the person that would go for Postman as it's a one stop shop for my needs from designing to mocking and finally documentation.
😧
Oh no! Hopefully some of these resources people are posting can help.
Re: your point on CORS, Smartbear (maker of the Swagger tools) are not the maintainers of the OpenAPI specification, and the official site / github repo don't contain such an article.