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）：

<dependencies>
  <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>
</dependencies>

配置类启用 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 插件示例）：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>5.2.1</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
        <generatorName>html2</generatorName>
        <output>${project.build.directory}/generated-docs</output>
      </configuration>
    </execution>
  </executions>
</plugin>

亦可使用 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 进行协作、版本管理与权限控制（适合企业场景）。

0 赞

0 踩