ubuntu swagger文档如何生成

在Ubuntu上生成Swagger文档的常见方法

1. 准备基础环境

在开始生成文档前，需安装Node.js和npm（Node.js包管理器），这是使用Swagger工具的前提：

sudo apt update
sudo apt install -y nodejs npm

2. 方法一：使用Swagger Editor（在线/离线）

Swagger Editor是可视化编辑OpenAPI规范的工具，适合快速创建和预览文档。

• 安装Swagger Editor：
  • 在线方式：直接访问Swagger Editor官网，无需安装。
  • 离线方式：下载Swagger Editor包（如swagger-editor.zip），解压后在目录下运行http-server（需提前安装http-server：sudo npm install -g http-server），启动后访问http://localhost:8080。
• 使用步骤：
  1. 导入现有swagger.yaml/swagger.json文件或新建文档。
  2. 编辑API信息（如标题、版本、路径、参数等）。
  3. 保存后，可直接在编辑器右侧预览交互式文档，或导出为JSON/YAML格式。

3. 方法二：编程方式生成（以Go语言为例，使用swag工具）

若项目使用Go语言，可通过swag工具根据代码注释自动生成Swagger文档。

• 安装swag工具：

  go install github.com/swaggo/swag/cmd/swag@latest
  

• 初始化文档： 在项目根目录运行swag init，生成docs目录（包含docs.go、swagger.json、swagger.yaml等文件）。
• 添加代码注释： 在Controller文件中添加Swagger注释，例如：

  // @Summary 获取用户信息
  // @Description 根据用户ID获取详细信息
  // @Tags Users
  // @Accept json
  // @Produce json
  // @Param id path int true "用户ID"
  // @Success 200 {object} User
  // @Router /users/{id} [get]
  func GetUser(c *gin.Context) {
      // 业务逻辑
  }
  

• 重新生成文档： 修改代码或注释后，再次运行swag init，工具会自动更新Swagger文档。

4. 方法三：集成到构建流程（以Spring Boot为例，使用SpringDoc）

若项目使用Spring Boot，可通过springdoc-openapi-ui依赖自动生成Swagger文档，适合Java项目。

• 添加依赖： 在pom.xml中添加以下依赖（以Maven为例）：

  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.14</version>
  </dependency>
  

• 配置Swagger： 创建配置类（如SwaggerConfig.java），启用Swagger并设置扫描路径：

  import io.swagger.v3.oas.models.info.Info;
  import io.swagger.v3.oas.models.OpenAPI;
  import org.springdoc.core.GroupedOpenApi;
  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  
  @Configuration
  public class SwaggerConfig {
      @Bean
      public GroupedOpenApi publicApi() {
          return GroupedOpenApi.builder()
                  .group("public")
                  .pathsToMatch("/**") // 扫描所有路径
                  .build();
      }
  
      @Bean
      public OpenAPI customOpenAPI() {
          return new OpenAPI()
                  .info(new Info()
                          .title("Spring Boot Swagger API")
                          .version("1.0")
                          .description("API文档自动生成"));
      }
  }
  

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

注意事项

• 若使用其他编程语言（如Python、Node.js），可选择对应的Swagger工具（如swagger-ui-express用于Node.js、flask-swagger-ui用于Python Flask）。
• 生成的文档可通过CI/CD流程（如GitHub Actions）自动化更新，确保文档与代码同步。