Ubuntu Swagger API文档怎么生成

在Ubuntu上生成Swagger API文档的常见流程

1. 准备开发环境

首先安装Node.js和npm（Node.js包管理器），这是使用Swagger工具的基础：

sudo apt update
sudo apt install -y nodejs npm

2. 安装Swagger核心工具

根据需求选择以下工具（任选其一即可）：

• Swagger Editor：在线/本地编辑OpenAPI规范的工具，支持实时预览文档。

  sudo npm install -g swagger-ui
  

• Swagger Codegen：根据OpenAPI规范生成客户端/服务器代码的工具（如Java、Python等）。

  sudo npm install -g swagger-codegen
  

• swagger-jsdoc：通过代码注释自动生成OpenAPI规范的工具（适合已有代码的项目）。

  sudo npm install -g swagger-jsdoc
  

3. 编写OpenAPI规范文件

OpenAPI规范（OAS）是Swagger文档的基础，通常为swagger.yaml或swagger.json格式。可通过以下两种方式创建：

• 手动编写：参考OpenAPI规范文档，定义API的基本信息（标题、版本）、路径（接口）、参数、响应等。示例（swagger.yaml）：

  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 Editor：下载Swagger Editor（如从官网），通过图形界面填写API信息，导出为swagger.yaml文件。

4. 生成Swagger文档

方式一：通过代码注释自动生成（适合已有项目）

若项目已有代码，可使用swagger-jsdoc从代码注释中提取API信息，生成OpenAPI规范：

swagger-jsdoc -c path/to/swagger-config.yaml -o path/to/output/swagger.json

其中，swagger-config.yaml是配置文件（定义注释解析规则），output/swagger.json是生成的规范文件。

方式二：使用Swagger Codegen生成客户端/服务器代码

若需要生成特定语言的客户端代码（如Java），可使用swagger-codegen：

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

其中，-i指定输入规范文件，-l指定生成语言（如java、python），-o指定输出目录。

方式三：集成到项目中自动生成（适合开发阶段）

若使用Spring Boot等框架，可通过注解和插件自动生成文档：

• 添加依赖：在pom.xml（Maven）中添加Swagger依赖：

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

• 配置Swagger：创建配置类启用Swagger：

  import org.springframework.context.annotation.Bean;
      
  import org.springframework.context.annotation.Configuration;
      
  import springfox.documentation.builders.PathSelectors;
      
  import springfox.documentation.builders.RequestHandlerSelectors;
      
  import springfox.documentation.spi.DocumentationType;
      
  import springfox.documentation.spring.web.plugins.Docket;
      
  import springfox.documentation.swagger2.annotations.EnableSwagger2;
  
  
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  
      @Bean
      public Docket api() {
      
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定Controller包
                  .paths(PathSelectors.any())
                  .build();
  
      }
  
  }
      
  

• 访问文档：启动项目后，访问http://localhost:8080/swagger-ui.html即可查看交互式文档。

5. 查看与测试文档

• Swagger UI：将生成的swagger.yaml/swagger.json文件导入Swagger UI（可通过swagger-ui-express或其他工具托管），通过浏览器访问查看交互式文档（支持接口测试、参数填写等功能）。
• 集成到项目：若使用Spring Boot，启动项目后直接访问/swagger-ui.html即可查看实时文档（文档随代码更新自动刷新）。

注意事项

• 确保OpenAPI规范文件符合规范（如使用正确的openapi版本、路径格式等），否则可能导致生成失败。
• 若使用注解方式，需在代码中正确添加Swagger注解（如@ApiOperation、@ApiParam），否则文档信息不完整。
• 对于大型项目，建议将Swagger集成到构建流程（如Maven/Gradle），实现文档自动生成与更新。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！