1. apidoc
2. documenting APIs
3. OpenAPI spec and generated reference docs

OpenAPI spec and generated reference docs

The OpenAPI specification provides a formal way of describing your REST API and includes all the reference sections mentioned in the previous section, Documenting API endpoints. Display frameworks such as Swagger UI can parse the OpenAPI specification and generate interactive documentation that lets users try out endpoints while learning about the API.

Sections in this chapter:

• Overview of REST API specification formats
• Introduction to the OpenAPI specification
• Create an OpenAPI specification document using Stoplight Studio's visual editor
• Step-by-step OpenAPI tutorial
• OpenAPI tutorial using Swagger Editor and Swagger UI: Overview
• Working in YAML
• Step 1: The openapi object
• Step 2: The info object
• Step 3: The servers object
• Step 4: The paths object
• Step 5: The components object
• Step 6: security object
• Step 7: The tags object
• Step 8: The externalDocs object
• Activity: Create an OpenAPI specification document
• Swagger UI tutorial
• Stoplight — visual modeling tools for creating your spec
• SwaggerHub introduction and tutorial
• Redocly tutorial -- authoring and publishing API docs with Redocly's command-line tools
• Integrating Swagger UI with the rest of your docs
• Demos of OpenAPI outputs using different tools
• Stoplight demo
• Swagger UI Demo
• Redoc demo