Swagger

Dunjia

2025-04-05

tool

Swagger

Swagger 是一个开源的 API 文档生成工具，它可以帮助开发者快速生成和维护 API 文档。Swagger 提供了一种标准化的方式来描述 RESTful API，使得 API 的使用者能够更容易地理解和使用 API。

SpringBoot 下的配置

配置 pom.xml

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.0.3</version>
</dependency>

knife4j-spring-boot-starter 是一个用于集成 Swagger 的 Spring Boot Starter，它提供了一些额外的功能和配置选项，使得 Swagger 的使用更加方便。

配置 WebMvcConfiguration

/**
 * 配置类，注册web层相关组件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    ...

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("xxx接口文档")
                .version("2.0")
                .description("xxx项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                // 扫描指定包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始进行静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

使用

在浏览器中访问 http://localhost:8080/doc.html 即可查看生成的 API 文档。
在 API 文档中，可以查看到所有的 API 接口，包括接口的请求方式、请求参数、响应结果等信息。同时，Swagger 还提供了在线测试接口的功能，可以直接在文档中测试接口的调用。
Swagger 还支持多种格式的 API 文档导出，包括 JSON、YAML 等格式，可以方便地与其他工具进行集成。

常用注解

Swagger 提供了一些常用的注解，可以帮助开发者更好地描述 API 接口。以下是一些常用的注解：

@Api: 用在类上，例如 Controller 类，用于描述整个 API 的基本信息，包括 API 的名称、描述、版本等。
@ApiModel: 用在类上，例如 entity、DTO 类，用于描述模型类的基本信息，包括模型类的名称、描述等。
@ApiModelProperty: 用在属性上，用于描述模型类的属性信息，包括属性的名称、描述、是否必填等。
@ApiOperation: 用在方法上，例如 Controller 方法，用于描述 API 接口的基本信息，包括接口的名称、描述、请求方式等。

@Api(tags = "用户相关接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable("id") Long id) {
        // ...
    }

    @ApiOperation(value = "创建用户", notes = "创建一个新的用户")
    @PostMapping
    public User createUser(@RequestBody User user) {
        // ...
    }
}

Gin 下的配置

Swagger 在 Gin 中的配置相对简单，只需要安装相关的依赖包，并在代码中进行简单的配置即可。

1
2
3

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

Swagger 提供了一个命令行工具 swag，可以用来生成 Swagger 文档。使用 swag init 命令可以自动扫描代码中的注释，并生成 Swagger 文档。

swag init

package main

import (
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   "net/http"
)
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
   g.JSON(http.StatusOK,"helloworld")
}

func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1"
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld",Helloworld)
      }
   }
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")

}

在代码中，我们使用了 @BasePath 注解来指定 API 的基础路径，使用 @Router 注解来指定 API 的路由。Swagger 会根据这些注解自动生成 API 文档。
在 main 函数中，我们使用 ginSwagger.WrapHandler 来将 Swagger 文档挂载到 Gin 路由上。这样，在访问 http://localhost:8080/swagger/index.html 时，就可以查看生成的 API 文档了。
在代码中，我们使用了 @Summary、@Description、@Tags、@Accept、@Produce、@Success 等注解来描述 API 接口的基本信息。Swagger 会根据这些注解自动生成 API 文档。

最终代码结构如下：

.
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

访问http://localhost:8080/swagger/index.html 即可查看生成的 API 文档。

Swagger

SpringBoot 下的配置

Gin 下的配置

参考