What is redoc?
Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions. By default Redoc offers a three-panel, responsive layout:
- The left panel contains a search bar and navigation menu.
- The central panel contains the documentation.
- The right panel contains request and response examples.
See GitHub repo.
How to use redoc
One of the simplest ways to use redoc is via Docker. If openapi.yaml is in the current directory the following command will create api.html:
docker run --rm -it -v "$PWD:/data" redocly/redoc \
build-docs /data/openapi.yaml -o /data/api.html
and this produces HTML like this:
Can we do anything else with redoc?
Yes we can lint an API specification too which will list errors and warnings:
docker run --rm -v $PWD:/data redocly/cli lint /data/openapi.yaml
No configurations were provided -- using built in recommended configuration by default.
validating /data/openapi.yaml...
[1] ../data/properties/question.yaml:7:13 at #/TaskType/properties/id/type
`type` can be one of the following only: "object", "array", "string", "number", "integer", "boolean", "null".
Did you mean: string ?
5 | $ref: "../properties/_index.yaml#/Type"
6 | id:
7 | type: str
| ^^^
8 | description: The unique identifier for this media.
9 | url:
...
❌ Validation failed with 3 errors and 9 warnings.