chapter twelve

12 API visualization

 

This chapter covers

  • Generating OpenAPI specifications for a project, previously known as Swagger API.
  • Accessing OpenAPI project specifications
  • Visually inspecting project endpoints with Swagger UI
  • Utilizing the Design-First approach to developing APIs. The process of creating an API design before implementing it with code.

Originally developed in 2010 as the Swagger specification, a way for defining machine-readable interfaces to describe RESTful services. In 2016 Swagger specification was rebranded as the OpenAPI specification under a new OpenAPI Initiative sponsored by the Linux Foundation. Other benefits to an OpenAPI specification of a service include:

  • Creating interactive documentation of a service
  • Automation of test cases based on a specification
  • Generating clients or services aligned with a specification

The ability to visualize an API, including its' definition and expected behavior, can be tremendously helpful when a developer wants to interact with an external service. Particularly when the service is developed by another team or another company entirely. Why? How does it help?

12.1 Viewing OpenAPI documents with Swagger UI

12.1.1 Enabling OpenAPI

12.1.2 Swagger UI

12.2 MicroProfile OpenAPI

12.2.1 Application information

12.2.2 Customize Schema output

12.2.3 Defining operations

12.2.4 Operation responses

12.2.5 Tagging operations

12.2.6 Filtering OpenAPI content

12.3 Design-First development

12.3.1 OpenAPI file base

12.3.2 Mixing file and annotations

12.4 Code First or OpenAPI first?

12.5 Summary