Approaches to REST API documentation

This repository accompanies a talk on Approaches REST API documentation.

The approaches considered all have one thing in common - they keep a connection between the API reference and the code. In other words - they give some guarantees about the API reference and the implementation code being in sync. This is a very important characteristic of an API reference.

The code in this repository is used to illustrate the different approaches.

All these scenarios use the same REST API implemented with spring-boot.

The plain API is contained in the plain branch.

Slides

The presentation slides reside here

Considered Approaches

Introspection

This approach relies on application code being introspected to get the information about the REST API.

The library used to implement this approach is SpringFox.

Branch: spring-fox-documented

Test-driven

This approach uses a test-driven approach to generate important parts if an API reference.

Two variants are presented here:

• Use spring-restdocs and AsciiDoc - see branch restdocs-documented
• Use restdocs-openapi on top of spring-restdocs - see branch openapi-documented

Design first

In this approach the focus is on the API design. The connection to the code is established using Atlassians's swagger-request-validator.

Branch: open-api-request-validator-documenated