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