How do you create API documentation?
I'm trying to do some market research for a product I'm working - Bulletin.io, and I'd love to hear how the IH developer community is creating API documentation.
Couple of questions:
- Do you generate your documentation off a Swagger/Openapi spec or is it manual?
- Do you use a paid solution, open-source solution, or have you built something custom?
Note - this is for public facing/customer API documentation.
Trending on Indie Hackers
I use Slate:
https://github.com/slatedocs/slate
To generate these docs:
https://developers.bannerbear.com
Which is hosted on Netlify.com
As an indiehacker / small business this works great for me.
I've worked in a larger organization where the API needed a whole ecosystem around it as multiple teams were responsible for contributing to the docs - so you needed things like doc versioning, draft / approval controls, and for the spec to be auto-generated from Swagger etc.
I can't think of what would be a better solution for me currently than just using git / markdown / slate and publishing to Netlify but perhaps this is one of those things that you need to be shown, rather than it being an innate pain-point that people are aware of.
Hi @yongfook, just came across this thread, your website and product. Well done with all the progress and achievements you've made! I also see that your documentation site has been updated as well :) do you mind sharing what you use now to generate your docs as of 2022?
I migrated to something custom built.
It's pretty simple actually, it just uses Middleman (which is what Slate also uses) and parses a list of endpoints to build the site. I just wanted more control over the layout and structure etc. Probably could have patched Slate, but rolling my own was cleaner and faster in the end.
Thanks for the response! It definitely is a step up and is very sleek as well :) It looks very professional, well done! 👏
Thanks for this. That does sound like a pretty seamless setup and can understand why it's easy.
Makes sense regarding the larger organization - I've had similar experiences. I'm not trying to solve all those problems (just yet), but I do think they exist. I'm more focused on providing beautiful public API documentation for companies where their API is a key part of their product.
Does the underlying codebase generate an OpenAPI/Swagger spec out of the box? I'm not sure what you use, but many of them do this for you. For example, I typically use Django/DRF and this library generates the spec for you. If this was true, it would probably be easier for you? Just use Bulletin, input the destination of the spec, and the rest is handled :)
No intention to use a commercial solution. It is not only a cost issue, we don't want the code base to be accessed by a 3rd party, given the doc is generated from annotation, it simply makes it difficult to get a 3rd party to generate the doc without giving away the source code.
Interesting. Wouldn't you be able to just expose the Swagger/OpenAPI file to a third party, without having to expose the underlying code?
Yes it's possible to separate the code from the annotation, but the idea when using a 3rd party is to have less work to do.
Understood and agree. I was thinking a public URL would automatically be generated that exposes the OpenAPI/Swagger spec and Bulletin would be able to access that.
Stripe have just released Markdoc, a Markdown-based authoring framework that powers their public documentation. Looks interesting.
Hi @kyle, I'm Sébastien, founder of Bump (https://bump.sh). We have created Bump for the exact same reason you have started to work on Bulletin, and I'm glad to see a new comer in this space!
There is clearly a market: we have customers paying to host their OpenApi based documentation, just because we provide an elegant UI. Most of them automatically generate their OpenAPI files for internal documentations, but for public docs it's generally a manual process.
I hope this helps, good luck with Bulletin!
Hi Sébastien - thanks for the response and awesome to hear you're having success. I think there's space for several solutions here :)
We are using Redocly https://github.com/Redocly/redoc to host our Swagger/OpenAPI specs. Very easy to get started/host as static files
Highly recommend this as well! We did some research to find the best open source doc solution for Swagger/OpenAPI and Redoc had some of the best design along with very in depth support for lots of OpenAPI features.
ADDITIONAL THOUGHTS: Worth pointing out building a business in this space. There are companies like Readme and Stoplight. Not saying you shouldn't compete with them, but understand their problems -- they have many. Look for a podcast with the founder of Readme -- he talks about how hard the business-model is and why they pivoted to their new API analytics offering. Want to nudge you in how you approach this space, think different.
Thanks for providing this. I've looked into Apiary before, but not too much into their Blueprint format. I'll take more of a look. As far as GraphQL, that's been getting mentioned a couple times in the feedback - I need to jump in further to see what the documentation experience is like.
I found the Readme podcast - will definitely have a listen.
Thanks again!
Hi, I am using RestCase (https://www.restcase.com). I am creating and maintaining the API documentation there.
Also, I can recommend using ApiBldr (https://apibldr.com) for building the API as an OpenAPI spec, and then you can generate documentation using any tool you want.
Thanks,
Guy
ApiBldr looks cool. Thanks!
I'm using GraphQL, where all documentation is essentially integrated within the API. Should be pretty much self explanatory.
Thanks. To be completely honest, I haven't used GraphQL (yet) and can't comment. But this is good insight into the fact GraphQL's is self-documenting.
I am doing the same. If a field or a query is not clear, I just put a comment explaining it in the schema and it is there whenever someone is browsing in GraphiQL or the playground
I use gitbooks for Scrapingproject API. I would love to try your Product.
Awesome! Gitbook is great - I've demoed their product before. They're just not as focused on the API portion (even though they do support), but I do think they work well for building guides.
I saw your name added to the email list - I'll keep you notified. Thanks!
We use Postman. You can see the RiteKit API's dosc here
Our API Demo Dashboard
Looks good and thanks for providing. Are you happy with Postman?
Yes. We've moved from Mashape to Apiary to Postman. Best for us to-date.
I generally prefer RAML, but I've also used Swagger/Open API for API docs.
RAML is similar but a more compact way of specifying your endpoints. Once you finish, it will generate docs and even some automated testing-related tools for you. It's a newer, less entrenched but IMO better spec: https://raml.org/
I don't give my customers API docs at the moment, but I'm using VuePress for general technical docs to share with customers.
Thanks - I'm not aware of RAML. It looks pretty clean/simple from checking out their docs - I'll check this out further.
Oh, my! This actually is a funny story. I have been waiting for a better, easier solution to document APIs FOREVER now and was just talking with a friend of mine about building a platform that solves this.
Glad to see you working on it! I usually just do manually because what is out there (in my opinion) still does not beat manual. Although one day I hope it does!
Funny - same here (no surprise)!
When you say "manually," is there any tool you use now to write these out manually?
Imho Stripe has the best API docs in town. They were a huge inspiration for us when writing our own API docs for Feather (https://feather.id/docs/api). We write our docs manually, but this does put extra effort on us to keep them in sync as the API evolves
Agreed re Stripe docs. That's actually what I'm modeling the docs after and was my initial post the other day: https://www.indiehackers.com/post/generate-stripe-like-api-documentation-4b8743e213
Your docs look nice. If you wanted to take the more automated approach, do you have Swagger/OpenAPI definitions that are auto-generated currently?
Good luck with Feather. I was actually checking it out the other day, based off of some other post you replied to. I think there's an opportunity there for smaller cos who aren't quite ready for Okta/Auth0.
Ah thanks, I think so too but we'll have to prove it out! :)
We don't have a Swagger/OpenAPI definition at the moment, but it's something we'll likely look to add eventually. I've never worked with those in the past and when starting a new project like this, I usually tend to ignore unfamiliar technologies in the interest of cutting scope. (I treat learning-driven, throw-away projects much differently)
One of our "issues" at the moment is just that we hacked our website together and most of our content is written directly into React components (the API itself is much cleaner 🤣). It's not a burning issue, but we've been thinking about ways to pull out the content into a CMS. Auto generating docs directly from an API schema sounds really promising in that regard.
I think there are number of APIs that would really benefit from auto-generated documentation like you're providing. However one of my larger concerns with regards to a service like Bulletin (particularly as an author of Feather) is that we believe clearer documentation and tutorials are one our opportunities for differentiation. As such I'm a little more inclined to "build" our docs in-house rather than "buy".
All that being said, there's one area I think you could really look into. I used to work on the payments team at Uber. At that company, there are literally thousands of micro-services, most offering an API other services can integrate with. As you can imagine, the documentation around each service is inconsistent, stale, or missing altogether. If each service at Uber had "Stripe-like documentation" auto-generated from an API spec, that likely could have saved me weeks of scheduling meetings with other teams to figure how to integrate our services.
So I have a hunch that for more publicly-facing commercial APIs, devs are little more likely to want to own their documentation rather than delegate it. But for internal private-facing APIs, documentation is a huuuge pain for everyone and no one wants to spent time on it (shipping flashy features is much more likely to result in a promotion).
Hopefully this perspective helps, but take my hunches with a grain of 🧂!
Thanks - definitely a helpful perspective.
If you're using an API framework, does it support a OpenAPI/Swagger spec generation out of the box? I use Python/Django/DRF and this library does much of that work for you. But I do agree with not using new technologies - I'm the same way. This might just be a quick win :)
That's good feedback regarding Uber. I do feel, though, that with internal documentation, you're less concerned about the look/design of it. I do agree keeping the docs up to date is absolutely necessary and a Swagger/OpenAPI spec helps with that, but there are then existing tools that'll give a (good-enough) UI on top of it.
We're not using any big framework like Django on the backend for Feather, just vanilla Go. But thanks for the tip!
I think your sense is right that look/design of internal documentation is not the most important factor. But it still does play a role sometimes. Just getting an advocate for a particular technology at a company can do a lot. For example, at one point we switched from OpenGrok to Sourcegraph as a "code search" tool. I don't know the story behind the transition or why it happened, but the much better ease-of-use was the most apparent thing to me once it did happened.
It's possible you may want to pull customers from something like Gitbook (or target the devs that would traditionally choose Gitbook) for a specialized API use-case.
Hi Kyle,
Good question, over time I have done this every way in the book. But the way I did it for (Knoma|https://www.knoma.io/developer/paywith) was to design the page our selves and use a cloud solution to handle the actual content CMS.
In our case, this was Confluence by Atlassian, that has been great for all our internal documentation needs, and with their API it was pretty easy to call the documents we wanted to be public. I wouldn't recommend confluence for you as it can be expensive and not designed for this, it worked for us as we were already using it heavily internally.
I see you are trying to find a better solution, so let me know how you get on. I am certainly intrigued. And if you want to implement confluence support eventually let me know.
Thanks for the response and feedback. Agreed Confluence wouldn't be the right tool for this. I've used for internal documentation, but not so much for external and definitely not for an API.
If you're interested in following along, definitely put your email in bulletin.io and I'll send you an alert once it's ready!
If you have used it for internal use you know how important a tool like Confluence can be. It is the one 'source of truth' for all documentation for companies big and small. If I was a client, I personally wouldn't want to copy all our documentation over to another platform. That was the reason we decided to build a solution out using the Atlassian API, that and cost. Since then we have been able to build out scalable docs for all our current future documentations.
I guess my question is what problem are you trying to solve? Personally, for me, your product would cause more problems than it solves. But please convince me otherwise.
I do agree having one source of truth is nice and in many cases, it's the holy-grail that you're always striving for, but never quite able to achieve. So it's definitely cool you were able to get there.
Have you used OpenAPI/Swagger before? It allows you to define your API in a standard structure that's widely accepted. From this, you can have automatic tests generated, API docs generated :), etc. I'm merely providing a beautiful interface on top of this, so it makes your API documentation a breeze to use for customers.
Use GraphQL
I like postman
https://learning.postman.com/docs/postman/api-documentation/documenting-your-api/.
Agreed - Postman is nice. There were a couple things missing and they pushed the postman ecosystem too much for my liking, but do think they do a nice job.
I usually use write Open API specs, redoc-cli and host the static content on github pages. "Auto-sync" via CI (circle, GH actions etc).
That being said the spec files could easily be hosted & rendered somewhere else.
Awesome. This is exactly how I see the setup with bulletin working - just setting up auto-sync with your OpenAPI spec and the static content gets updated.
This comment was deleted 5 years ago.
Gulp. Sounds like a pretty involved project. The language support is something I want to add, but haven't found a solid way to do that out of the box yet (e.g. community support open-source project) and worried about building that solo from scratch.