Introduction
Througout this post I am describing the path it took me to specify my own REST API's (API specifications) as well as how to document them in a browasable and accessable way.
It focues on tools to simplify your work but also includes topics like mocking and linting.
A summary in git project can be found at the bottom
If you are developing REST API's for internal or external use, you will need to document it at some point. To do so, probably the best approach is to follow a given standard. Some of the goals we can achieve with this, is:
- fast starting point for new developers
- follow the same principles
- standardize and follow best practices
- save time (compared to writing your own specs)
- use tools (document, try out, test, mock, stub)
There are two major specifications available:
Raml is a project of MuleSoft (Salesforce) and therefore also used in their API and Integration platform.
OpenAPI originates from Swagger, who donated their specifications to the OpenAPI Initiative.
Swagger has similar to Mulesoft, interesting open and closed source project for the entire API lifecycle.
Finding your right choice of tools
Regardless if you have already a ready deployed API or you are designing a new one, there is a bit of a learning curve before you have your own specifications ready to distribute. Thats where commercial offerings like those mentioned from Mulesoft and Swagger come in handy. Their platforms provide UI's to create them, so you don't have to write them directly in json or yaml but instead use a tool.
There are a lot of different commercial offerings from other providers as well, and then there is open source!
I am briefly going to describe some tools I used along the way and what I am using in the last couple of months and found best work flow for myself.
Creation / Editing
Swagger Editor
As its name may suggest, Swagger Editor helps you writing your definition. Simultineously, you get a playground to test your specifications - as you write - with your endpoint. The preview is provided with the Swagger UI project.
You can run Swagger Editor as a npm dependency, from a docker image or even include the distribution version in your own product.
Pros:
- Convert to Json/Yaml
Insert options
Server generator
Client generator
**Integrates Swagger UI**
Cli for linting and building
Cons:
- Does not handle file splitting
I personally prefer to have individual files for the models and use them on build time by reference. Its better maintainable that way.
In your IDE
Some IDE have plugins which assist you writing your definition. You still writing the definition in a text editor but assist you with linting, references and also the general structure and naming.
Example with a plugin for Visual Studio Code
Pros:
- No adjustment in workflow, use your usual IDE
- Installable through your IDE
- Linting
Cons:
- No native documentation
Stoplight Editor
One of my favourite Open Source projects!
The Stoplight Studio is built with Electron and therefore can be installed ony "any" OS. It has visual support in the UI for most of the things you can do with the OpenAPI specifications, is actively developed and you can get involved on github.
Pros:
- Lots of built in functionality right where you need it, like:
- Structures like objects, arrays etc
- Required fields
- Property types
- Query parameters
- Create from json
- Defaults
- Examples
- Tags
- Components
- Implements git
- Manages multiple APIs
- Additional publishing features
- API Sandbox
- Client generator
- Auto linting
- Mocking
- Http client
Cons:
- Only uses provided structure
- Does not support responses component to reuse with $ref.
- No native documentation
Reported issues have been resolved by the maintainers!
The creation and publication seems to be part of their commercial offerings.
Linting
Linting is the process of testing your API definition agains the offical specifications.
A good editor already comes with a linter included. However, there are linters which can be used from the command line and therefore also be used your deployment pipeline!
Some good linters include:
- IBM openapi-validator
- Redoc
- Spectral, included in Stoplight editor or use cli
- Speccy, using oas-validator
Examples:
Spectral
```
spectral lint myApi.yaml
```
Speccy
```
speccy lint myApi.yaml
```
Speccy in Docker
```
docker run -it --rm -v ${PWD}:/project/ wework/speccy lint myApi.yml
```
Documenting
Creating a documentation based on the API.yml or API.json .
Redoc creates beautiful and browsable human readable API documentation. Instead of using Redoc directly, I use [Speccy](https://github.com/wework/speccy) which bundles some tools used not only to create a documentation, but also for linting.
A [live example of how a documentation may look with redoc can be found here](http://redocly.github.io/redoc/). You can even provide a link to your API specifications to preview your own documentation.
Mocking
Prism is another open sources project of stoplight. It comes as npm package or docker container and can be used to mock your api by referencing your specifications.
Some of its features:
- hot reloading
- proxy (proxy request to live endpoint)
What about Postman
Postman has a great client to organize your requests in collections, store properties as variables, supports various authentication methods and even lets you store the responses.
Postman uses their own specifications but one could create a postman collection by (automatically) converting a OpenApi scheme.
However, those generated postman specification will allways (correct me if I am wrong) have a `"string"` value, rather than using the propertys default specified in the specs. This could just be an problem by the converters I tested but I found it evenly fast to copy paste the json if I want to use Postman for testing.
In the meantime, I am almost exclusively using the http client built into Stoplight Editor whitch you find under "Try it".
Therefore I truly control (as of version control) all my APIs with git and don't have to rely on sharing API's on commerciall offered platforms.
Conclusion
I document my API's with OpenAPI (yaml or json) specifications and invite stake holders to participate using git.
The Specifications are created by Stoplight Editor, at the same time I am certain that my definition fullfill the OpenAPI specifications but additionaly lint them using oas-validation.
Sometimes it makes a difference or an error can be faster resolved using more than one linter.
Once I made a modification I also resolve all referenced files to one API.yaml file.
I then use speccy to auto generate and update the documentation.
For bigger projects, I include the linter, documentation generator and eventually the server or client generators in my continuous integration and deployment pipline.
The one thing I would like to improve is to have a playground included in my documentation. Speccy provides me a very nice documentation, but their playground seems to become a commercial offering. Thus I have to fall back on the Swagger UI which is a great tool but my documentation is less complete or in a separate place.
With small tradeoffs, all required tools are available under open source.
Some platforms like Stoplight, Swagger or Mulesoft provide you with a more comprehensive toolset.
I crated a small repository base on the petstore example which is available at gihub.