Generating API docs with the OpenAPI 3.0 spec, Redoc, and auto-generated snippets

  • Introduction
  • The OpenAPI 3.0 Specification
  • Redoc Integration
  • Conclusion & Final Thoughts

Introduction

The OpenAPI 3.0 Specification

Root level object fields

  • openapi*
  • info*
  • servers
  • paths*
  • components
  • security
  • tags
  • externalDocs

Implementation example

Figure 1 — Paths example in the YAML openAPI 3.0 format
Figure 2 — Components example in the YAML openAPI 3.0 format

Redoc Integration

VSCode + Extensions

  • ritwickdey.liveserver — Used to host a dynamic HTML file which will be updated upon save, allowing us to see and correct things as we go!
  • 42crunch.vscode-openapi — Used for debugging of the OpenAPI specification. It also helps with navigating through sections since it adds a menu on the left side of visual studio.

Redoc Development

Redoc Deployment

sudo apt install node (or preferably directly from the website)
npm install redoc-cli
npx redoc-cli bundle your_file.yaml

Integrating auto-generated code snippets

Conclusion & Final Thoughts

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Miguel Saraiva

Miguel Saraiva

Software Engineer looking to learn & share knowledge.