一、導(dǎo)入依賴

        <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>

二团甲、創(chuàng)建swagger配置

??在Application.java同級，創(chuàng)建Swagger2的配置類Swagger2：

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Value("${swagger.enable}")
    private Boolean enable;

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api接口")
                .description("Api接口的描述")
                .termsOfServiceUrl("http://www.baidu.com/")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build()
                .enable(enable);
    }
}

@ Configuration：spring boot 加載配置黍聂。
@EnableSwagger2：啟用Swagger2躺苦。
createRestApi()：創(chuàng)建Api的基本信息。RequestHandlerSelectors.basePackage是通過掃描該路徑下的所有Controller定義的API产还，并產(chǎn)生文檔內(nèi)容（除了被@ApiIgnore指定的請求）匹厘。
.enable(enable)：通過配置文件控制swagger2是否啟用。在配置文件中配置swagger.enable為“true”或“false”脐区。一般正式環(huán)境會關(guān)閉swagger功能愈诚。

三、配置資源路徑

??如果繼承了WebMvcConfigurationSupport牛隅，則需要重新指定靜態(tài)資源（不配置的話會報No mapping for GET /swagger-ui.html錯誤）：

@Configuration
public class CorsConfig extends WebMvcConfigurationSupport {

    private MyInterceptor myInterceptor;

    @Autowired
    public CorsConfig (MyInterceptor myInterceptor){
        this.myInterceptor = myInterceptor;
    }

    // 注冊過濾器
    @Bean
    public FilterRegistrationBean<RepeatedlyReadFilter> repeatedlyReadFilter() {
        FilterRegistrationBean registration = new FilterRegistrationBean();
        RepeatedlyReadFilter repeatedlyReadFilter = new RepeatedlyReadFilter();
        registration.setFilter(repeatedlyReadFilter);
        registration.addUrlPatterns("/*");
        return registration;
    }


    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(myInterceptor).addPathPatterns("/**");
    }

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

四炕柔、添加接口文檔內(nèi)容

import cn.hutool.http.HttpStatus;
import cn.hutool.json.JSONObject;
import com.xyf.scriptkill.util.RestMessage;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@Api(tags="測試控制器")
@RestController
public class TestController {

    @ApiOperation(value="測試get", notes="")
    @ApiImplicitParams({
            @ApiImplicitParam(name="name",value="姓名",required=true,paramType="query"),
            @ApiImplicitParam(name="address",value="地址",required=true,paramType="query"),
    })
    @GetMapping("/api/gettest")
    public RestMessage getTest(
            @RequestParam(value = "name", required = true) String name,
            @RequestParam(value = "address", required = true) String address
    ){
        RestMessage restMessage = new RestMessage();
        restMessage.setSuccess(true);
        restMessage.setMessage("返回成功！");
        restMessage.setData(null);
        restMessage.setCode(HttpStatus.HTTP_OK);
        return restMessage;
    }

    @ApiOperation(value="測試post")
    @ApiResponses({
            @ApiResponse(code=400,message="請求參數(shù)沒填好"),
            @ApiResponse(code=404,message="請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name="jsonParams",value="json",paramType="body")
    })
    @PostMapping("/api/posttest")
    public RestMessage postTest(
            @RequestBody JSONObject jsonParams
    ){
        RestMessage restMessage = new RestMessage();
        restMessage.setCode(HttpStatus.HTTP_OK);
        restMessage.setData(jsonParams);
        restMessage.setMessage("返回成功媒佣！");
        restMessage.setSuccess(true);
        return restMessage;
    }
}

• @Api："用在Conntroller類上匕累，表示對類的說明：

  1. tags= 說明該類的作用，可以在UI界面上看到配置的內(nèi)容默伍。
  2. value= 在UI界面上看不到到欢嘿，可不配置。

• @ApiOperation：用在Conntroller類的方法上也糊，說明方法的用途炼蹦、作用：

  1. value= 說明方法的用途、作用显设。
  2. notes= 方法的備注說明框弛。

• @ApiImplicitParams： 用在Conntroller類的方法上，表示一組參數(shù)說明：

  • @ApiImplicitParam： 用在@ApiImplicitParams注解中捕捂，指定一個請求參數(shù)的各個方面
    1. name： 參數(shù)名稱瑟枫。
    2. value： 參數(shù)的漢字說明斗搞、解釋。
    3. required： 參數(shù)是否必須項慷妙。
    4. paramType： 參數(shù)放在哪個地方僻焚。
       • header：參數(shù)在request header獲取，@RequestHeader膝擂。
       • query：請求參數(shù)的獲取虑啤，@RequestParam。
       • path：以地址的形式提交架馋，@PathVariable狞山。
       • body：請求參數(shù)的獲取，@RequestBody叉寂，僅支持Post萍启。
       • form：以form表單的形式提交 僅支持Post。
    5. dataType：參數(shù)類型屏鳍，默認(rèn)String勘纯，其它值如dataType="Integer"。
    6. defaultValue：參數(shù)的默認(rèn)值钓瞭。

• @ ApiResponses： 用在Conntroller類的方法上驳遵，表示一組響應(yīng)：

  • @ ApiResponse： 用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息
    1. code： 數(shù)字山涡，例如400堤结。
    2. message： 信息內(nèi)容。
    3. response： 拋出異常的類佳鳖。
       
       @ ApiResponses

• @ ApiModel： 用于響應(yīng)類上霍殴，表示一個返回響應(yīng)數(shù)據(jù)的信息：

  • @ ApiModelProperty： 用在屬性上，描述響應(yīng)類的屬性系吩。

import cn.hutool.json.JSONObject;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel(description= "返回響應(yīng)數(shù)據(jù)")
public class RestMessage implements Serializable {

    @ApiModelProperty(value = "是否成功")
    private boolean success;

    @ApiModelProperty(value = "返回對象")
    private JSONObject data;

    @ApiModelProperty(value = "狀態(tài)碼")
    private Integer code;

    @ApiModelProperty(value = "返回信息")
    private String message;

    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }

    public JSONObject getData() {
        return data;
    }

    public void setData(JSONObject data) {
        this.data = data;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

ok，啟動Spring boot妒蔚，輸入http://localhost:8081/swagger-ui.html

swagger