Linux上Swagger API文档如何生成

Linux上生成 Swagger API 文档的实用方案

一 前置准备

• 安装 Java 11+（OpenJDK）：sudo apt update && sudo apt install openjdk-11-jdk。
• 准备 OpenAPI/Swagger 规范文件（如 swagger.yaml 或 swagger.json），用于驱动文档生成与展示。
• 可选：安装 Docker，便于快速运行 Swagger Editor/UI 或 OpenAPI Generator 容器化服务。

二 方式一 运行时集成生成文档 Spring Boot 示例

• 添加依赖（Maven，Springfox 2.x）：

  
    io.springfox
    springfox-swagger2
    2.9.2
  
  
    io.springfox
    springfox-swagger-ui
    2.9.2
  

• 配置类启用 Swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
      .paths(PathSelectors.any())
      .build();
  }
}

• 启动应用后访问 http://localhost:8080/swagger-ui.html 查看交互式文档（端口按实际调整）。

三 方式二 代码注解生成规范并导出静态文档

• Node.js + Express 使用 swagger-jsdoc + swagger-ui-express：
  • 安装：sudo npm install -g swagger-jsdoc；sudo npm install -g swagger-ui-express。
  • 代码示例：

  const express = require('express');
  const swaggerUi = require('swagger-ui-express');
  const swaggerJsdoc = require('swagger-jsdoc');
  
  const options = {
    definition: {
      openapi: '3.0.0',
      info: { title: 'API', version: '1.0.0' }
    },
    apis: ['./routes/*.js'] // 含 JSDoc 注解的文件
  };
  const swaggerSpec = swaggerJsdoc(options);
  
  const app = express();
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  app.listen(3000, () => console.log('Docs: http://localhost:3000/api-docs'));
  

• 构建后生成的 swagger.json/swagger.yaml 可配合任意 Swagger UI 渲染。

四 方式三 使用 OpenAPI Generator 从规范生成文档与客户端

• 准备 openapi-generator-cli.jar（建议 v5.2.1 及以上）。
• 生成静态 HTML 文档（示例）：

java -jar swagger-codegen-cli.jar generate \
  -i path/to/swagger.yaml \
  -l html2 \
  -o path/to/output/docs

• 生成客户端代码（示例）：

java -jar swagger-codegen-cli.jar generate \
  -i path/to/swagger.yaml \
  -l java \
  -o path/to/output/java-client

• 集成到构建（Maven 插件示例）：

  org.openapitools
  openapi-generator-maven-plugin
  5.2.1
  
    
      generate
      
        ${project.basedir}/src/main/resources/swagger.yaml
        html2
        
${project.build.directory}/generated-docs
      
    
  

• 亦可使用 Docker 运行生成器 CLI，便于无侵入式集成。

五 方式四 使用 Docker 快速运行编辑器与 UI

• 启动 Swagger Editor（设计/校验规范）：

docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0

• 启动 Swagger UI（展示规范）：

docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

• 浏览器访问：http://<服务器IP>:38080（Editor），http://<服务器IP>:38081（UI）。

六 实用建议

• 规范优先：维护一份 OAS 3.0 的 YAML/JSON，通过工具链生成文档与客户端，避免手工维护多份文档。
• 展示多样化：除 Swagger UI 外，可考虑 ReDoc 等开源渲染器，以获得不同的展示风格与导航体验。
• 自动化与协作：将规范与生成步骤纳入 CI/CD，并在团队中使用 SwaggerHub 进行协作、版本管理与权限控制（适合企业场景）。

以上就是关于“Linux上Swagger API文档如何生成”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！

简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm