swagger在ubuntu上的文档生成

Ubuntu 上 Swagger OpenAPI 文档生成与发布

一 准备环境

• 安装 Node.js 与 npm（用于本地运行 Swagger Editor/UI 或作为静态服务器）
  • 命令：sudo apt update && sudo apt install -y nodejs npm
• 可选安装 Docker（用于容器化运行 UI 或生成器）
  • 命令：sudo apt install -y docker.io
• 说明：Swagger 现已演进为 OpenAPI Specification（OAS），以下流程同时适用于 Swagger 2.0 与 OAS 3.x 的编写、展示与发布。

二 方式一 使用 Swagger Editor 编写与导出

• 本地运行 Editor（推荐）
  • 下载发布包并启动：

    wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
    tar -xvf v3.16.1.tar.gz
    cd swagger-editor-3.16.1
    npm install
    npm install -g http-server
    http-server -p 8080
    

  • 访问：http://localhost:8080，在编辑器中导入或编写 swagger.yaml/swagger.json，实时预览与校验。
• 仅用于展示时，也可直接运行官方容器：

  docker pull swaggerapi/swagger-ui-express
  docker run -p 8080:8080 swaggerapi/swagger-ui-express
  

  访问 http://localhost:8080 使用 UI（默认加载示例规范，可通过环境变量或挂载自定义规范）。

三 方式二 在现有服务中集成 Swagger UI 展示文档

• Node.js + Express 示例（静态托管或中间件托管）
  • 安装依赖：npm i express swagger-ui-express yamljs
  • 代码示例（保存为 index.js）：

    const express = require('express');
    const swaggerUi = require('swagger-ui-express');
    const YAML = require('yamljs');
    const app = express();
    const swaggerDocument = YAML.load('./swagger.yaml'); // 或 swagger.json
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
    const PORT = process.env.PORT || 3000;
    app.listen(PORT, () => console.log(`Server on ${PORT}`));
    

  • 启动：node index.js，访问 http://localhost:3000/api-docs。
• Docker 快速托管任意规范文件

  docker run -p 8080:8080 \
    -e SWAGGER_JSON=/app/swagger.json \
    -v $(pwd):/app \
    swaggerapi/swagger-ui-express
  

  将你的 swagger.json 放在当前目录即可在 http://localhost:8080 查看。

四 方式三 从代码注解自动生成 OpenAPI 规范

• Go 项目（swaggo/swag）
  • 安装：go install github.com/swaggo/swag/cmd/swag@latest
  • 生成：swag init（生成 docs 目录）
  • 在代码中添加注释后再次 swag init 更新文档。
• Spring Boot 项目
  • 使用 springdoc-openapi（推荐，适配新版本 Spring Boot）
    • 依赖：

      <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.1.0</version>
      </dependency>
      

    • 访问：http://localhost:8080/docs
  • 或使用 Springfox（旧方案）
    • 依赖：

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
      </dependency>
      

    • 访问：http://localhost:8080/swagger-ui.html。

五 规范校验与代码生成

• 校验与本地预览
  • 使用 openapi-generator-cli 校验与启动本地预览服务：

    docker run --rm -p 8080:8080 openapitools/openapi-generator-cli
    

    在容器内执行 validate 校验，或使用其预览能力进行快速检查。
• 代码生成（客户端/服务端存根）
  • 示例（生成 Java 客户端）：

    java -jar openapi-generator-cli-2.4.21.jar generate \
      -i ./path/to/swagger.yaml \
      -l java \
      -o ./output
    

  可生成多语言客户端、服务器桩、API 文档等，便于前后端并行开发。