Springboot集成Swagger2

Springboot集成Swagger2

前言

​ 多年以前写过一篇 springMVC整合swagger(亲自试验完全可用)，但随着springboot的流行，今天记录一下springboot集成swagger2的使用过程，swagger3的集成类似只不过依赖调整了一下，后面会提到。

集成

添加maven依赖

<properties>
	<swagger.version>2.9.2</swagger.version>
</properties>
<!-- swagger2	-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

自定义Docket

@Configuration
@Component
public class Swagger2Config {
	@Bean
    public Docket api() {
        // 2.0 http://localhost:8080/swagger-ui.html#/
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置文档基本信息，可不配置。
                .enable(true)
                .select()
                .paths(PathSelectors.regex("^/api/.*$"))
            	//.apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))扫描包
                .build();
    }
    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Hello World", "http://xxx.xxx.com/Hello World", "Hello World@gmail.com");
        return new ApiInfo("springboot集成swagger2", // 标题
                "springboot集成swagger2", // 描述
                "v1.0", // 版本
                "http://XXX/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

其他Docket配置详见参考文档中的Docket documentation

增加启用swagger注解

在启动类上增加注解

@EnableSwagger2 //开启Swagger2的自动配置
@SpringBootApplication
public class SpringbootSwagger2Application {...}

启动后访问 http://ip:port/swagger-ui.html

常用注解

• @Api：用于类上，会将注解的类作为swagger资源

  • tags：API分组标签，具有相同标签的API将会被归并在一组内展示
  • value：如果tags没有定义，value将作为Api的tags使用
  • description：描述

  @Api(value = "/user", description = "用户相关API")
  

• @ApiOperation：用于方法上，描述方法

  @ApiOperation(
            value = "获取所有用户",
            notes = "获取所有用户",
            response = UserResponse.class,
            tags = {""})
  

• @ApiImplicitParams：注解ApiImplicitParam的容器类（数组）

  @ApiImplicitParams({
  	@ApiImplicitParam(name = "id", value = "用户ID", dataType = String.class, required = true)
  })
  

• @ApiImplicitParam：用在方法上描述参数

  • name：参数名称
  • value：参数的简短描述
  • required：是否为必传参数
  • dataType：参数类型，可以为类名，也可以为基本类型（String，int、boolean等）

  @ApiImplicitParam(name = "id", value = "用户ID", dataType = String.class, required = true)
  

• @ApiResponse：必须在@ApiResponses中使用，描述状态码，并不能描述具体的返回信息

  @ApiResponses(value = {
          @ApiResponse(code = 200, message = "request success.") 
  })
  

• @ApiResponses：用于表示一组响应

• @ApiModel：用于实体上，描述实体

  • value：别名，默认为类名

  @ApiModel(value="用户", description="用户实体")
  

• @ApiModelProperty：用于实体属性上，描述属性

  • value：描述
  • example：示例值
  • required：是否必须

  @ApiModelProperty(value = "用户id",example="1",required=false)
  

总结

​ 以上就是springboot集成swagger2的全部内容，是不是非常简单，与springmvc复杂的配置不同，只需几行代码就搞定了，至于swagger3的集成与swagger2本质上没什么太大的区别，主要是注解和依赖的调整，具体参考springfox即可，已经写的很全面了。

参考文档

springfox documentation

Docket documentation

springfox