温馨提示×

Debian系统中Swagger文档生成

小樊
39
2025-09-16 23:52:41
栏目: 智能运维

在Debian系统中生成Swagger文档,可按以下步骤操作:

  1. 安装工具

    • 安装Node.js和npm:sudo apt update && sudo apt install nodejs npm
    • 安装Swagger工具:
      • 用npm安装swagger-jsdoc(生成文档):sudo npm install -g swagger-jsdoc
      • 用npm安装swagger-ui-express(展示文档):sudo npm install -g swagger-ui-express
      • 或下载Swagger UI压缩包手动部署。
  2. 编写API规范

    • 创建swagger.yamlswagger.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 } ```。 
  3. 生成文档

    • 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
  4. 集成与访问

    • 用Express托管Swagger UI:创建app.js文件,引入swagger-ui-express并指定文档路径,启动服务后访问http://localhost:3000/api-docs
    • 可选:通过Nginx反向代理,将Swagger UI绑定到域名或路径。

说明

  • swagger-jsdoc适合从代码注释自动生成文档,swagger-codegen适合从规范文件生成多语言代码或文档。
  • 工具安装及配置可参考官方文档,根据项目需求选择合适方式。

0