SpringBoot与Swagger2整合

编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

SpringBoot + Swagger2 使用教程

一、引入依赖

<parent>
     <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>2.0.4.RELEASE</version>
      <relativePath/> <!-- lookup parent from repository -->
</parent>

 <!-- swagger start -->
        <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</version>
        </dependency>
 <!-- swagger end -->

二、添加配置

@EnableSwagger2 //开启在线接口文档
@Configuration //标记配置类
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                .apis(RequestHandlerSelectors.basePackage("cn.chinaunicom.srigz.goods.admin"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("商品管理系统Rest接口测试")
                .version("1.0")
                .description("API 描述")
                .build();
    }
}

或者

@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2Config {
    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：某公司_用户信息管理系统_接口文档")
                        .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                        .contact(new Contact("一只袜子", null, null))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hehe.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

三、编写接口文档

swagger2 基本使用

@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiParam 描述方法的参数
@ApiImplicitParam 描述方法的参数

@ApiImplicitParams 描述方法的参数(Multi-Params)

以上的注解一般用在controller层

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
	public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id)

@Api(value = "数据对象管理" ,tags = {"数据对象的接口"})
public class DataObjectController {
    @Autowired
    private DataObjectService dataObjectService;

    @ApiOperation(value="查询归属此数据对象的数据字段信息", notes="输入对象编码")
    @RequestMapping(value = "/api/v1/dataObject/{code}", method = RequestMethod.GET)
    public Map getOne(@ApiParam(required = true, value = "对象编码") @PathVariable String code){
        return ActionHelper.responseOk(dataObjectService.getList(code));
    }

@ApiModelProperty 用于方法，字段；表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

@ApiIgnore 忽略某类/方法/参数的文档

常用注解也可以查阅一下网址：

https://www.cnblogs.com/fengli9998/p/7921601.html

四、查阅接口文档

编写文档完成之后，启动当前项目，在浏览器打开：

http://localhost:8080/swagger-ui.html#/