Reputation: 697
I am using redocly for generating API documentation. Currently redocly generates API documentation for endpoints (paths), but does not generate schema documentation. This blog on their website explains how to generate the schema section by settingschemaDefinitionsTagName
value to Schema
in the configuration file, but it does not seem to be working here.
While I can individually tag each component/schemas
definition with <SchemaDefinition schemaRef="#/components/schemas/{SchemaName}" />
it does not seem to be a scalable solution.
Does anyone know of a solution for this?
Here is my .redocly.yaml
configuration file
organization: example-org
extends:
- recommended
apis:
[email protected]:
root: ./api-def.yaml
theme:
openapi:
schemaDefinitionsTagName: Schemas
This is my api-def.yaml
file
openapi: "3.0.3"
info:
title: Sample Application
version: "0.1"
servers:
- url: http://localhost:3000/
description: localhost
- url: https://myapp.dev.example.com/
description: dev server
- url: https://myapp.qa.example.com/
description: qa server
- url: https://myapp.example.com/
description: prod server
paths:
/cars:
post:
tags:
- Cars
operationId: "createCar"
summary: Create Car
description: Create a new Car.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Car"
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Car"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/cars/{id}:
put:
tags:
- Cars
operationId: "updateCar"
summary: Update Car
description: Update an existing car
parameters:
- name: id
in: path
required: true
description: Id of the car to be updated.
schema:
type: string
format: objectId
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Car"
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Car"
'400':
description: Bad Request. The request body has errors.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
'404':
description: Not Found. Car with the `:id` parameter not found.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
get:
tags:
- Cars
operationId: "getCar"
summary: Get Car.
description: Get car represented by id.
parameters:
- name: id
in: path
required: true
description: Id of the car to be looked up.
schema:
type: string
format: objectId
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Car"
'404':
description: Not Found. Question with the `:id` parameter not found.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Car:
type: object
properties:
id:
type: string
format: objectId
manufacturerId:
type: string
format: objectId
description:
type: string
description: detail description of the car
configuration:
$ref: "#/components/schemas/Configuration"
category:
type: string
description: Category of the car
enum:
- sedan
- suv
- hatchback
- atv
createdAt:
type: string
format: date
updatedAt:
type: string
format: date
required:
- content
-
Configuration:
oneOf:
- $ref: "#/components/schemas/V6Configuration"
- $ref: "#/components/schemas/V8Configuration"
V6Configuration:
type: object
properties:
id:
type: string
description:
type: string
V8Configuration:
type: object
properties:
id:
type: string
description:
type: string
Error:
type: object
properties:
name:
type: string
code:
type: number
description: this would correspond to the HTTP status code of the response.
description:
type: string
data:
type: object
description: this object would contain any additional data related to the error.
and this is the command I am using to generate the API documentation
redocly build-docs --output api-def.html api-def.yaml
And this is what generated documentation looks like.
Upvotes: 2
Views: 992