openapi-generator: Generate Docs from OpenAPI
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs produces static HTML documentation from an OpenAPI description.
OpenAPI Generator (the maintained successor to swagger-codegen) emits clients, servers, and docs from a spec. The html and html2 generators produce a documentation page for CI.
What it does
openapi-generator-cli generate reads the input spec (-i), runs the named generator (-g), and writes output to -o. Generators html and html2 produce API documentation; swagger-codegen generate -l html is the equivalent in the older tool.
Common usage
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs
# validate the spec before generating
openapi-generator-cli validate -i openapi.yaml
# the legacy tool
swagger-codegen generate -l html -i openapi.yaml -o docsOptions
| Flag | What it does |
|---|---|
| -g <generator> | Generator name (html, html2, and many clients) |
| -i <spec> | Input OpenAPI/Swagger file or URL |
| -o <dir> | Output directory |
| validate -i <spec> | Validate the spec without generating |
| --skip-validate-spec | Skip spec validation before generating |
| -c <config.json> | Generator configuration file |
In CI
Run openapi-generator-cli validate as a gate, then generate. The CLI needs Java on the runner (it is a JAR); use the official Docker image to avoid that. Pin the generator version, since output and available generators change across releases.
Common errors in CI
Can't load config file, ... or The spec file is not valid come from an unreadable input or a spec that fails validation; run validate -i to see the specifics. Error: Unable to access jarfile or command not found means Java or the CLI JAR is missing on the runner. [main] ERROR ... generator not found means the -g name is wrong for your version.