Spring boot中使用Swagger2

問題

最近須要作接口開發，給客戶端們調用，可是我又不想寫文檔，據說REST風格的接口都在用Swagger作IDL（Interface description language），中文就是接口描述語言，簡單的說就是給調用方的開發人員看的。具體能夠看危機百科：接口描述語言。

Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
    <scope>compile</scope>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
    <scope>compile</scope>
</dependency>

Gradle

...
ext {
    springfoxSwagger2Version = "2.8.0"
}
...
dependencies{
    implementation "io.springfox:springfox-swagger2:${springfoxSwagger2Version}"
    implementation "io.springfox:springfox-swagger-ui:${springfoxSwagger2Version}"
}
...

主配置

package com.xxx.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

  @Bean
  public Docket businessApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.hngytobacco.budget.controller"))
        .paths(regex("^/businesses.*"))
        .build()
        .apiInfo(metaData());
  }

  private ApiInfo metaData() {
    return new ApiInfoBuilder()
        .title("Budget")
        .description("REST API for budget")
        .version("0.0.1")
        .contact(new Contact("YaLin", "https://my.oschina.net/fxtxz2", "zhangyl@xxx.com.cn"))
        .build();
  }

  @Override
  protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry
        .addResourceHandler("swagger-ui.html")
        .addResourceLocations("classpath:/META-INF/resources/");

    registry
        .addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");
  }
}

而後，啓動spring boot，訪問http://localhost:8080/swagger-ui.html就能夠了，效果以下：

以上就是基本的Swaager配置。

還有關於controller和Java bean的配置：

@RestController
@RequestMapping(value = "/businesses")
@Api(value = "業務實例", description = "操做業務實例")
public class BusinessController {
...
@ApiOperation(value = "根據登陸用戶獲取業務實例列表", response = Iterable.class)
  @ApiResponses(value = {
          @ApiResponse(code = 200, message = "成功查找到業務實例列表"),
          @ApiResponse(code = 404, message = "用戶沒有角色"),
          @ApiResponse(code = 401, message = "沒有權限")
  })
  @GetMapping("/list/{username}")
  public ResponseEntity<List<BusinessVO>> getBusinessByUser(
  ...

效果：

java bean的配置：

import io.swagger.annotations.ApiModelProperty;

/** 業務VO */
public class BusinessVO {
  @ApiModelProperty(notes = "業務實例主鍵")
  private long id;
  /** 業務名稱 */
  @ApiModelProperty(notes = "業務實例名稱")
  private String name;

  /** 業務模板id */
  @ApiModelProperty(notes = "業務實例對應的業務模板id")
  private long templateId;

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public long getTemplateId() {
    return templateId;
  }

  public void setTemplateId(long templateId) {
    this.templateId = templateId;
  }


}

效果以下：

參考：

SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2