How can I document my API?
I need to document APIs for my last project, I like the https://readme.io/, but they are out of my price range.
Any ideas/alternatives?
I need to document APIs for my last project, I like the https://readme.io/, but they are out of my price range.
Any ideas/alternatives?
Hey Nino,
I was in the same situation and I ended up using Swagger to document the API. It's a bit verbose if you use the YML file directly but it's not different from writing code.
Because my API is not stable I stopped updating the doc but you can find the original repo for Squadlytics here: https://bitbucket.org/squadlytics/squadlytics-swagger. Feel free to fork it and adapt it. It contains a shell script that uses a Docker image to launch the app, which means that you could use the same kind of logic to host it online with a PaaS that supports Docker.
For the docs website themselves I'm using Gatsby.js with Netlify. That makes the whole thing free. I've created a Starter Kit for other folks that would want like me to save a few bucks/month
Cheers,
Sten
Swagger is my go to for documenting APIs. Swagger plus swashbuckle (https://github.com/domaindrivendev/Swashbuckle) makes it very easy to get up and running in a .NET environment. I point it to my service layer and let swashbuckle dynamically build out my API as calls are added.
Thnx for the answer, it seems like an overkill for me :(
Edit: let's put the links directly here.
Some other options are:
Here's a HN discussion that might help: https://news.ycombinator.com/item?id=8912897
I also found https://www.getpostman.com, it seems that they also have feature for documenting APIs.
We use postman in our team and it is amazing to collaborate on APIs and create and share documentation.
Yeah, I was also going to suggest Postman for publishing your API docs. The advantage of that is that the Postman collection is also available for people to use in the tool.
While I was still with Auth0 I created and published our Postman collections and in the process had to interact with the Postman people a few times. They were always very helpful and nice to interact with.
I started to use Postman recently, for testing API. Will definitely try publishing option.
I liked using Apiary.io — I thought Swagger was overkill
Apiary looks interesting. From the description at apiary.io it looks like this expects the resulting endpoint to be hosted at apiary/oracle - is that right? (Nothing wrong with that, per se, but that's meaningfully different than swagger.)
I used Apiary a couple of years ago: We hosted endpoints on our own server and used Apiary for the neat markdown documentation formatting
I use https://apiblueprint.org to write my API specs and created a renderer for Laravel https://github.com/M165437/laravel-blueprint-docs
Hey Nino!
You can build your API with https://stdlib.com and get documentation for free (see: https://stdlib.com/@messagebird/lib/numbers as an example of docs). It’s a Function as a Service platform specifically designed for building APIs that has a bunch of fancy goodies; auto-generated SDKs, auth, rate limiting, billing, interactive examples, local development and a CLI, automatic type coercion from query parameters, and more! (Think of it like a supercharged AWS Lambda + API Gateway.)
The one thing to take note of is that the API design style is more akin to namespaced methods than traditional REST. You’ll end up with something more akin to Stripe’s API than a traditional swagger / crud API. :) it’s reasonably priced, with a free tier that should suit your dev needs.
Disclaimer: I’m the founder :)
Thnx, looks exactly as the tool I need, will dive into more thoroughly.
I used https://github.com/lord/slate for my manatoo docs here: https://docs.manatoo.io.
It's just markdown so it's really easy to get started, deploy (I used github pages), and, to a certain extent, maintain. However, it is static documentation so it might not be the best choice if your API changes a lot.
I use Swagger
Since I don't see it mentioned yet, I like to use Hitch http://www.hitchhq.com for my APIs, on top of swagger. I like it because it lets you configure update notifications for people to follow, gives you a widget to display on your site for people to click, etc. Hitch is a startup from KW.
I have a small tool that I created recently for creating documentation. It is simple and generic however, and doesn't have any API documentation specific features.
I would suggest restunited.com, i am using it and it also generates clients for various languages.
All you need is to create the swagger files.