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#/
posted @ 2018-10-30 11:00  Slive  阅读(177)  评论(0编辑  收藏  举报