chapter twelve

12 API visualization

 

This chapter covers

  • Generating OpenAPI (previously known as Swagger UI) specifications for a project
  • Accessing OpenAPI project specifications
  • Visually inspecting project endpoints with the 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 a way for defining machine-readable interfaces to describe RESTful services, in 2016, the 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 follow:

  • 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 Customizing the 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 the file and annotations

12.4 Code first or OpenAPI first?

Summary