在Node.js中使用多个API文档作为Swagger？

Question

我为一个项目版本化了我的API，因此它有两个文件夹v1和v2，其中包含不同的API。现在为了实现v1和v2的swagger，我在app.js中编写了以下代码。

最初的回答：

我已经为项目版本化了我的API，因此它有两个文件夹v1和v2，分别包含不同的API。为了实现v1和v2的swagger，我在app.js中编写了以下代码。

// Swagger definition
// You can set every attribute except paths and swagger
const swaggerDefinition = {
    swagger: '2.0',
    info: {
        // API informations (required)
        title: 'API', // Title (required)
        version: '1.0.0', // Version (required)
        description: 'Used for  api documentation', // Description (optional)
    },
    host: `localhost:3000`, // Host (optional)
    basePath: '/v1', // Base path (optional)
};

// Options for the swagger docs
const optionsV1 = {
    // Import swaggerDefinitions
    swaggerDefinition,
    // Path to the API docs
    // Note that this path is relative to the current directory from which the Node.js is ran, not the application itself.
    apis: ['./app/v1/docs/*.yaml']
};

const optionsV2 = {
    // Import swaggerDefinitions
    swaggerDefinition,
    // Path to the API docs
    // Note that this path is relative to the current directory from which the Node.js is ran, not the application itself.
    apis: ['./app/v2/docs/*.yaml']
};
optionsV2.swaggerDefinition.basePath = "/v2"
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpecV1 = swaggerJSDoc(optionsV1);
const swaggerSpecV2 = swaggerJSDoc(optionsV2);
// const swaggerDocument = require('./app/v1/docs/swagger.json');
// app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.use('/v1/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecV1));
app.use('/v2/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecV2));

最初的回答： 如果我访问 /v1/docs 或 /v2/docs，它总是显示 v2 的 API 文档。因此，这里最后一行是写给 v2 的，它总是只显示 v2 的文档。请建议如何支持多个 API？

- TechChain

---

可能是Swagger-ui-express模块，仅实例化最后定义的文档的重复问题。 - Helen

Swagger 上的 CSS 对你来说正常吗？我尝试了一切，但是页面没有样式。 - Rodrigo Manguinho

Answer 1

这是Swagger UI中的已知问题。请使用以下格式路由请求：

var swaggerHtml = swaggerUi.generateHTML(swaggerDocument, swaggerUiOpts)
app.use('/api-docs-html1', swaggerUi.serveFiles(swaggerDocument, swaggerUiOpts))
app.get('/api-docs-html1', (req, res) => { res.send(swaggerHtml) });

更新的代码：

var swaggerHtmlV1 = swaggerUi.generateHTML(swaggerSpecV1, optionsV1)
var swaggerHtmlV2 = swaggerUi.generateHTML(swaggerSpecV2, optionsV2)

app.use('/v1/docs', swaggerUi.serveFiles(swaggerSpecV1, optionsV1))
app.get('/v1/docs', (req, res) => { res.send(swaggerHtmlV1) });

app.use('/v2/docs', swaggerUi.serveFiles(swaggerSpecV2, optionsV2))
app.get('/v2/docs', (req, res) => { res.send(swaggerHtmlV2) });

请查看以下链接获取更多细节： https://github.com/scottie1984/swagger-ui-express/issues/65

- Sahil

Answer 2

尝试以下配置：

app.use('/v1/docs', swaggerUi.serve, (...args) => swaggerUI.setup(swaggerSpecV1)(...args));
app.use('/v2/docs', swaggerUi.serve, (...args) => swaggerUI.setup(swaggerSpecV2)(...args));

- Roy Lee

Answer 3

根据答案转换了我的代码

var swaggerHtmlV1 = swaggerUi.generateHTML(swaggerSpecV1, optionsV1)
var swaggerHtmlV2 = swaggerUi.generateHTML(swaggerSpecV2, optionsV2)

app.use('/v1/docs', swaggerUi.serveFiles(swaggerSpecV1, optionsV1))
app.get('/v1/docs', (req, res) => { res.send(swaggerHtmlV1) });

app.use('/v2/docs', swaggerUi.serveFiles(swaggerSpecV2, optionsV2))
app.get('/v2/docs', (req, res) => { res.send(swaggerHtmlV2) });

- TechChain