Spring Swagger配置教程

Swagger 可为 Spring Boot 工程生成清晰的接口文档，从而减少前后端开发人员的沟通所带来的不必要麻烦。

下面就介绍如何在工程中集成 Swagger 文档

1. 项目创建

新建 Spring Boot 工程，在 Maven 中导入 Swagger 相关依赖。

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

2. Bean配置

新建 SwaggerConfig 配置类，添加如下内容。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        // 接口类所在包路径
        String apiPath = "xyz.ibudai.controller";
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage(apiPath))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot Demo")
                .description("这是一个简单的 Swagger API 演示")
                .contact(new Contact("ibudai", "www.ibudai.xyz", "ibudai56@163.com"))
                .version("1.0.0-SNAPSHOT")
                .build();
    }
}

3. 基本使用

完成上述配置后下面介绍如何在接口中添加描述信息。

• @ApiOperation

  @ApiOperation 用于设置接口摘要，简单描述接口用途。

• @ApiImplicitParams

  @ApiImplicitParams 用于设置接口具体描述，其参数内容参考下表。

  方法	作用
  name	说明参数名称。
  value	说明参数介绍。
  dataType	说明参数类型。
  paramType	说明参数请求方式。
  required	说明参数是否必须。

  @RestController
  @RequestMapping("api/swagger")
  public class SwaggerController {
  
      @GetMapping("get")
      @ApiOperation(value = "Swagger - 测试接口")
      @ApiImplicitParams({
              @ApiImplicitParam(name = "id", value = "编号", dataType = "string", paramType = "query", required = true),
              @ApiImplicitParam(name = "msg", value = "消息", dataType = "string", paramType = "query", required = false)
      })
      public String get(String id, String msg) {
          return id + "_" + msg;
      }
  }
  

4. 工程配置

在工程配置文件中添加如下内容，若未设置 context-path 则后续访问地址则无需添加相应配置。

server:
  port: 9090
  servlet:
    # Swagger 地址: localhost:9090/budai/swagger-ui.html
    context-path: /budai

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

5. 效果测试

打开浏览器访问地址：localhost:9090/budai/swagger-ui.html，出现下图内容说明成功。