Spring boot中使用Swagger2

为什么80%的码农都做不了架构师？>>>   

问题

最近需要做接口开发，给客户端们调用，但是我又不想写文档，听说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

转载于:https://my.oschina.net/fxtxz2/blog/2048738