Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。當(dāng)項(xiàng)目前后端分離或者后臺(tái)給APP提供接口時(shí)，這時(shí)候使用swagger來(lái)管理接口還是很方便的，省去了很多開(kāi)發(fā)人員對(duì)接的時(shí)間。

先來(lái)個(gè)圖展示下效果

image.png

接下來(lái)開(kāi)始實(shí)現(xiàn)這個(gè)功能

• 首先pom.xml引入依賴(lài)

        <!-- Swagger2強(qiáng)大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強(qiáng)大RESTful API文檔 -->

• 然后開(kāi)始創(chuàng)建Swagger的配置文件

@Configuration
@EnableSwagger2
public class Swagger2 {
  // Swagger2默認(rèn)將所有的Controller中的RequestMapping方法都會(huì)暴露，
  // 然而在實(shí)際開(kāi)發(fā)中，我們并不一定需要把所有API都提現(xiàn)在文檔中查看，這種情況下，使用注解
  // @ApiIgnore來(lái)解決，如果應(yīng)用在Controller范圍上，則當(dāng)前Controller中的所有方法都會(huì)被忽略，
  // 如果應(yīng)用在方法上，則對(duì)應(yīng)用的方法忽略暴露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項(xiàng)目的RESTful APIs")
              .description("Sword項(xiàng)目的RESTful APIs")
              .termsOfServiceUrl("http://www.itdecent.cn/u/61959c6c46fa")
              .contact("David inner")
              .version("2.0")
              .build();
  }

}

• 最后去你具體的controller配置,就簡(jiǎn)單舉兩個(gè)列子

/**
     * 刪除
     * 方法功能說(shuō)明
     * 創(chuàng)建時(shí)間 2017年7月25日 下午10:59:17
     * 開(kāi)發(fā)者 david
     * @參數(shù)： @param ids
     * @參數(shù)： @return 
     * @return： Result
     */
    @ApiOperation(value = "刪除企業(yè)", notes = "根據(jù)url的ids來(lái)指定刪除對(duì)象或者對(duì)象集")
    @ApiImplicitParam(name = "ids", value = "企業(yè)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("刪除成功!");
    }
    
    /**
     * 保存企業(yè)
     * @param company
     * @return
     */
    @ApiOperation(value = "保存/修改企業(yè)", notes = "根據(jù)Company對(duì)象操作企業(yè)")
    @ApiImplicitParam(name = "company", value = "企業(yè)詳細(xì)實(shí)體user", required = true, dataType = "Company")
    @ResponseBody
    @RequestMapping(value="/save",method=RequestMethod.POST)
    public Result save(Company company){
        return  companyService.save(company);   
    }

• 訪問(wèn)地址
  http://localhost:8088/sword2.0/swagger-ui.html
  因?yàn)槲遗渲昧俗约旱腸ontext-path,具體項(xiàng)目具體看

image.png

這里如果不加@ApiIgnore的話會(huì)把你指向的包里面的controller全部生成展示出來(lái)，這樣swagger2就被完美的集成到你的項(xiàng)目中了。最后羅列下關(guān)于swagger的一些注解

@Api：修飾整個(gè)類(lèi)，描述Controller的作用
@ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API 
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit