A couple of months ago I read an article by Kin Lane about efforts that try to create shareable API docs. Personally, I am a strong fan of creating your API definitions upfront, because it makes it easier to have an estimate of how it is going to look like for your client to integrate with your service, and also for your team to develop clients and tests. If you are interested on those matters, you can always have a look at a previous presentation I had made a couple of years ago.
This article is more focused though on one of the efforts mentioned by Kin. This is called APIs.guru and is an open source effort to create public documents on swagger from existing APIs( documenting public APIs in OpenAPI(fka Swagger) format). Starting from there, with existing tooling like the awesome API transformer you can generate RAML, WADL, API Blueprints and whatever they support or to plan. Another interesting alternative is it’s open-source analog api-spec-converter (when they will support more output formats).
It was not long before I starred the github project and Ivan (the mastermind behind the whole thing) contacted me and we started chatting about it.
What exactly is APIs.guru?
The overall project’s goal is to create a machine-readable Wikipedia for REST APIs with the following principals:
- Open source, community driven project.
- Only publicly available APIs (free or paid).
- Anyone can add or change an API, not only API owners.
- All data can be accessed through a REST API.
Building Around APIs.guru
Listed below are some of the core integration
- https://any-api.com – Documentation and Test Consoles for Public APIs
- https://sdks.io – Explore Automatically Generated SDKs
- http://www.cenit.io – Social Data and Business Integration platform
- commandcar – Curl on steroids
- https://datafire.io – allows you to process and transfer data between APIs, databases, and more
- Material Swagger UI Hub – testing and exploring hub for Material Swagger UI demo
- Paw – The most powerful HTTP client for Mac – You can import definitions and directly play with the APIs, see how.
Also used as test suite in following projects:
- swagger-parser – Swagger 2.0 parser and validator for Node and browsers
- SwaggerProvider – F# Type Provider for Swagger
- ReDoc – Swagger-generated API Reference Documentation
Spreading the Word
Ivan has made it clear that he needs any help that anyone is willing to offer. Either
- or just some feedback.
When you try to create a community project and build something around it, you should be open to talking to people and listen to what they say. Ivan has all the right mindset to run something like this. It did not took long and I invited him to present at the API Athens Meetup
It was a nice event with tones and tones of API discussions and pizza as well!!