fastify-swagger生成OAS-3规范时markup富文本不生效如何解决？

你无需额外安装其他Fastify插件，你使用的fastify-swagger@4.8.4版本依赖的Swagger UI原生支持Markdown语法解析，无法识别格式的问题属于配置缺失，按以下步骤调整即可：

1. 插件注册时开启Markdown解析开关 #

注册fastify-swagger时，在uiConfig配置项中显式开启markdownEnabled参数：

fastify.register(require('fastify-swagger'), {
  openapi: {
    openapi: '3.0.3',
    info: {
      title: '你的API文档名称',
      version: '1.0.0'
    }
  },
  exposeRoute: true,
  routePrefix: '/docs', // 你的文档访问路径
  // 核心配置：开启Swagger UI的Markdown解析能力
  uiConfig: {
    markdownEnabled: true
  }
})

2. 确认Markdown内容的书写规范与位置 #

• 仅长文本字段支持Markdown解析：包括接口整体描述、接口operation的description字段、Schema的description字段等，summary字段为短文本字段，默认仅支持纯文本
• Markdown语法前后需保留空行：尤其是你使用的===一级标题、---水平分隔线/二级标题这类Setext风格语法，必须和上下内容之间空出一行才能被正确识别
  示例书写方式：

// 接口Schema定义示例
{
  schema: {
    description: `
接口功能说明
===
这是接口的核心说明内容
---
## 请求注意事项
* 所有参数必须为UTF-8编码
> 测试环境调用时请使用专属测试密钥
`,
    response: {
      200: {
        type: 'object',
        properties: {}
      }
    }
  }
}

3. 自定义嵌入HTML场景的额外配置 #

如果你是自行嵌入Swagger UI的HTML页面而非使用插件默认生成的页面，需要在SwaggerUIBundle初始化参数中也添加markdownEnabled: true配置：

const swaggerUi = SwaggerUIBundle({
  url: "/docs/json", // 你的OAS规范JSON接口地址
  dom_id: '#swagger-ui',
  markdownEnabled: true, // 手动开启Markdown解析
  // 其他你的自定义配置
})

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