spring boot 集成Swagger2

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。当项目前后端分离或者后台给APP提供接口时，这时候使用swagger来管理接口还是很方便的，省去了很多开发人员对接的时间。

先来个图展示下效果

image.png

接下来开始实现这个功能

• 首先pom.xml引入依赖

        <!-- Swagger2强大RESTful API文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!-- Swagger2强大RESTful API文档 -->

• 然后开始创建Swagger的配置文件

@Configuration
@EnableSwagger2
public class Swagger2 {
  // Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，
  // 然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解
  // @ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，
  // 如果应用在方法上，则对应用的方法忽略暴露API


  @Bean
  public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.daiwei.project")) //指向你的包
              .paths(PathSelectors.any())
              .build();
  }

  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
              .title("Sword项目的RESTful APIs")
              .description("Sword项目的RESTful APIs")
              .termsOfServiceUrl("http://www.jianshu.com/u/61959c6c46fa")
              .contact("David inner")
              .version("2.0")
              .build();
  }

}

• 最后去你具体的controller配置,就简单举两个列子

/**
     * 删除
     * 方法功能说明
     * 创建时间 2017年7月25日 下午10:59:17
     * 开发者 david
     * @参数： @param ids
     * @参数： @return 
     * @return： Result
     */
    @ApiOperation(value = "删除企业", notes = "根据url的ids来指定删除对象或者对象集")
    @ApiImplicitParam(name = "ids", value = "企业ids", required = true, dataType = "String")
    @ResponseBody
    @RequestMapping(value = "/delete",method=RequestMethod.DELETE)
    public Result delete(String ids) {
        List<Long> list = Utils.stringToLongList(ids, ",");
        for(Long id:list){
            companyService.companyDao.delete(id);
        }
        return Result.ok("删除成功!");
    }
    
    /**
     * 保存企业
     * @param company
     * @return
     */
    @ApiOperation(value = "保存/修改企业", notes = "根据Company对象操作企业")
    @ApiImplicitParam(name = "company", value = "企业详细实体user", required = true, dataType = "Company")
    @ResponseBody
    @RequestMapping(value="/save",method=RequestMethod.POST)
    public Result save(Company company){
        return  companyService.save(company);   
    }

• 访问地址
  http://localhost:8088/sword2.0/swagger-ui.html
  因为我配置了自己的context-path,具体项目具体看

image.png

这里如果不加@ApiIgnore的话会把你指向的包里面的controller全部生成展示出来，这样swagger2就被完美的集成到你的项目中了。最后罗列下关于swagger的一些注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API 
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit