Debian环境下Swagger API文档生成技巧
一 环境准备与版本选择
二 Node.js项目的落地步骤
sudo npm install -g swagger-jsdoc swagger-ui-express。swagger-jsdoc 的 definition 与 apis 扫描路由文件。const swaggerJsDoc = require('swagger-jsdoc');
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: { title: 'My API', version: '1.0.0' },
},
apis: ['./routes/*.js'], // 按实际路径调整
};
module.exports = swaggerJsDoc(swaggerOptions);
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocs = require('./swagger');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
app.listen(3000, () => console.log('http://localhost:3000/api-docs'));
三 Java Spring Boot项目的落地步骤
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
四 导出静态文档与离线浏览
pip3 install swagger-codegenswagger-codegen generate -i ./swagger.yaml -l swagger -o ./api-docs五 实用技巧与排错清单
apis 中精确指定路由/控制器目录,减少无关注释被解析。