Redocly生成API文档时无法自动生成Schema文档的解决方案求助

我正在使用Redocly生成API文档，目前工具仅能生成端点（paths）文档，无法生成Schema文档。Redocly官网博客提到可通过在配置文件中设置schemaDefinitionsTagName为"Schemas"来生成Schema板块，但该方法无效。手动为每个component/schemas定义添加<SchemaDefinition schemaRef="#/components/schemas/{SchemaName}" />标签的方式扩展性较差，请问是否有可行的解决方案？

相关文件信息 #

.redocly.yaml配置文件 #

organization: example-org
extends:
  - recommended

apis:
  autopilot@v0.1:
    root: ./api-def.yaml

theme:
  openapi:
    schemaDefinitionsTagName: Schemas

api-def.yaml API定义文件 #

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.

生成命令 #

redocly build-docs --output api-def.html api-def.yaml

文档预览截图 #

1. 修正配置文件中schemaDefinitionsTagName的位置 #

你当前将schemaDefinitionsTagName放在了theme.openapi层级下，这是错误的。正确的位置是在redoc节点下，修改后的.redocly.yaml如下：

organization: example-org
extends:
  - recommended

apis:
  autopilot@v0.1:
    root: ./api-def.yaml

redoc:
  schemaDefinitionsTagName: 'Schemas'

2. 修复API定义中的语法错误 #

你的api-def.yaml里Car schema的required字段存在语法问题：

• 包含不存在的字段content
• 最后有一个空的列表项-
  修正后的Car schema部分（可根据实际业务需求调整必填字段）：

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:
    - manufacturerId
    - description
    - configuration
    - category

3. 自动批量添加Schema定义标签（替代手动操作） #

如果修正配置后仍不生效，可以用脚本自动为所有schemas添加<SchemaDefinition>标签，避免手动操作的繁琐：
创建一个Node.js脚本add-schema-tags.js：

const fs = require('fs');
const yaml = require('js-yaml');

// 读取API定义文件
const doc = yaml.load(fs.readFileSync('./api-def.yaml', 'utf8'));

// 检查是否有info.description字段，没有则创建
if (!doc.info.description) {
  doc.info.description = '';
}

// 遍历所有schemas，添加SchemaDefinition标签
const schemas = doc.components.schemas;
for (const schemaName of Object.keys(schemas)) {
  doc.info.description += `<SchemaDefinition schemaRef="#/components/schemas/${schemaName}" />\n`;
}

// 写入修改后的文件
fs.writeFileSync('./api-def-updated.yaml', yaml.dump(doc));
console.log('Schema标签已自动添加到API定义文件');

执行脚本前先安装依赖：

npm install js-yaml

然后运行脚本：

node add-schema-tags.js

最后用更新后的文件生成文档：

redocly build-docs --output api-def.html api-def-updated.yaml

4. 验证Redocly版本 #

确保你使用的是最新版本的Redocly CLI，旧版本可能存在配置兼容性问题：

redocly --version

如果不是最新版，执行更新：

npm update -g @redocly/cli

内容的提问来源于stack exchange，提问作者Amrish