11 API documentation

In chapter 1, when we tried to define an application programming interface (API), we referred to it as a software platform that exposes tools and services that different computer programs can use to interact by exchanging data. Starting from this definition, we could say that the purpose of an API (including a web API) is to create a common place where independent and often-unrelated systems can meet, greet, and communicate by using a commonly accepted standard. These “actors” are mostly computer programs—such as websites, mobile apps, and microservices—that are implemented by other developers. For that reason, whoever takes on the task of designing, creating, and releasing a web API must acknowledge the existence and needs of a new type of user: the third-party developer, which brings us to this chapter’s topic.

11.1 Web API potential audience

11.1.1 Prospectors

11.1.2 Contractors

11.1.3 Builders

11.2 API documentation best practices

11.2.1 Adopt an automated description tool

11.2.2 Describe endpoints and input parameters

11.2.3 Add XML documentation support

11.2.4 Work with Swashbuckle annotations

11.2.5 Describe responses

11.2.6 Add request and response samples

11.2.7 Group endpoints into sections

11.2.8 Exclude reserved endpoints

11.3 Filter-based Swagger customization

11.3.1 Emphasizing the authorization requirements

11.3.2 Changing the application title