在Debian系统中生成Swagger文档,可按以下步骤操作:
安装工具
sudo apt update && sudo apt install nodejs npm
。swagger-jsdoc
(生成文档):sudo npm install -g swagger-jsdoc
。swagger-ui-express
(展示文档):sudo npm install -g swagger-ui-express
。编写API规范
swagger.yaml
或swagger.json
文件,定义接口路径、参数、模型等。例如:openapi: 3.0.0 info: title: Sample API version: 1.0.0 paths: /users: get: summary: List all users responses: '200': description: An array of users content: application/json: schema: type: array items: $ref: '#/components/schemas/User' components: schemas: User: type: object properties: id: { type: integer, format: int64 } name: { type: string } ```。
生成文档
swagger-jsdoc
生成HTML/Markdown等格式文档:swagger-jsdoc -i ./swagger.yaml -o ./docs
。swagger-codegen
(需先安装Java):java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l html2 -o ./output
。集成与访问
app.js
文件,引入swagger-ui-express
并指定文档路径,启动服务后访问http://localhost:3000/api-docs
。说明:
swagger-jsdoc
适合从代码注释自动生成文档,swagger-codegen
适合从规范文件生成多语言代码或文档。