Swagger 规范中,API 文档通常使用 YAML 或 JSON 格式编写,而在 Express 框架中,我们可以使用 swagger-jsdoc 和 swagger-ui-express 两个库来实现 Swagger 文档的生成和展示。

在 Express 应用中,可以将 Swagger 文档相关的内容分别存放在不同的文件中,然后通过 require() 函数引入即可。例如,可以将 Swagger 文档的配置信息放在 config.js 文件中:

// config.js

module.exports = {
  swaggerDefinition: {
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API documentation for My API'
    }
  },
  apis: ['./routes/*.js'] // 指定 API 路由文件的路径
}

在上面的示例中,我们定义了 Swagger 文档的基本信息,包括标题、版本号和描述等,并通过 apis 属性指定了 API 路由文件的路径。

接下来,在 Express 应用中,我们可以使用 swagger-jsdoc 库来生成 Swagger 文档的 JSON 数据:

// app.js

const express = require('express')
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')
const config = require('./config')

const app = express()

// 生成 Swagger 文档的 JSON 数据
const swaggerSpec = swaggerJSDoc(config)

// 使用 Swagger UI 展示 API 文档
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))

// 启动 Express 应用
app.listen(3000, () => console.log('Server started on port 3000'))

在上面的示例中,我们通过 swaggerJSDoc(config) 函数生成了 Swagger 文档的 JSON 数据,然后使用 swagger-ui-express 库展示了 API 文档。

需要注意的是,生成 Swagger 文档的 JSON 数据需要使用 swagger-jsdoc 库提供的注释语法,具体使用方法可以参考该库的文档。另外,如果 API 路由文件过多,也可以通过动态加载路由的方式来实现更好的模块化和可维护性。


原文地址: http://www.cveoy.top/t/topic/sAl 著作权归作者所有。请勿转载和采集!

免费AI点我,无需注册和登录