Sharing your API contract and documenting your APIs

API projects are special in the sense that they are essentially products that are entry points to data. This reiterates how important it is to maintain them well. APIs are products. This means that while it is important to maintain the code well to make your API well-suited for future development it is also important to share and document your API contract for your end users who are also usually developers. As a developer myself, I love when I have to integrate with an API that ships with a solid set of documentation. Equally, I frown upon it when the API doesn't have one! 

So what are some of the tools you can use to share your API contract and document them?

Please note that this is not an exhaustive list! There might be many more such tools or even ways to share your API Contract.

HTTP APIs

OpenAPI is the first name that comes to my mind when I think about HTTP API contracts. In the .NET world, there is NSwag and Swashbuckle, both of which are implementations of OpenAPI. Both these packages can be made available on your project to help test your API and even share the contract. The real magic here is a json file which contains all the details about your API that builds out into the beautiful SwaggerUI in your projects. This file is your Open API Specification(OAS) and can be written as a json or even a YAML file. However, the Swagger can become something that is very "developer-ey" in the technical documentation language world and also something that is way too coupled with your API. So I would suggest that you use a tool like Swaggerhub that can help you design your APIs, and form the OAS. Swaggerhub can generate interactive documentation as well but there are many other tools that can parse this YAML or JSON file and come up with spectacular interactive documentation

• Redoc - Live demo available at ReDoc Interactive Demo (redocly.github.io)
• Elements
• Postman

If you would like to understand the OAS in greater detail, please see the article I wrote for the Umbraco Advent Calendar last year.

gRPC Service

The key to any gRPC service is the .proto file. There is no way a client can consume your gRPC service without having a reference to the proto file. So in addition to the documentation, sharing your contract is even more important here.

I can think of these ways of sharing the proto files

• Share proto files as Nuget packages (works when you have .NET clients only)
• Store proto files in a central repository. Many of the Google public protos are available this way
• Git Submodules 

To document your gRPC service, I came across this very interesting tool GenDocu that can generate interactive documentation for your proto files. Comments added to proto files act as the starting point for your documentation. There is also an editor mode to further edit and enhance your documentation

GraphQL Server

GraphQL has this wonderful feature called Schema introspection whereby the API gathers information about itself. This has given rise to many "playgrounds" like GraphQL Playground, GraphiQL, Insomnia, Banana Cake Pop, Voyager etc. These tools expose the schema in a user-friendly manner in addition to SDL and can help developers greatly during the API integration process. 

There are further tools like SpectaQL, MagiDoc, DociQL, GraphDoc that can take the SDL from your GraphQL server and create interactive documentation. SpectaQL seems to be the top choice for many out there. It generates the initial documentation from the SDL and then gives you support for Markdown to edit and add your own content wherever needed. 

Having said that I particularly love the Shopify GraphQL documentation.

These are some of the tools that have come up in my research. Most of these tools support theming, embedding for easy hosting and even code samples that your client developers can use. Do you know any more? Let me know!!