注意:不同版本可能會遇到的坑不一樣，所以請儘量保持版本一致。

依賴

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

springboot 配置

package com.ysk.mybatiscrack.config;

import org.springframework.context.annotation.Bean;
import org.springframework
 
.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * 描述
 *
 * @author Y.S.K
 * @date 2018/6/9 11:46
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改為自己的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.ysk.mybatiscrack"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-api文件")
                .description("swagger接入教程")
                //服務條款網址
                .termsOfServiceUrl("https://blog.csdn.net/ysk_xh_521")
                .version("1.0")
                .contact(new Contact("Y.S.K", "http://ysk521.cn", "[email protected]"))
                .build();
    }
}

其實到這個時候已經整合好了，剩下就是註解的使用了。

先來一個可以用的

/**
 * @Api：用在請求的類上，表示對類的說明
    tags="說明該類的作用，可以在UI介面上看到的註解"
    value="該引數沒什麼意義，在UI介面上也看到，所以不需要配置"
 * @author Y.S.K
 *
 */
@Api(value="/test1", tags="測試介面模組")
@RestController
@RequestMapping("/test")
public class TestSwaggerController {

    /**
     * @ApiOperation：用在請求的方法上，說明方法的用途、作用
    value="說明方法的用途、作用"
    notes="方法的備註說明"
@ApiImplicitParams：用在請求的方法上，表示一組引數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
        name：引數名
        value：引數的漢字說明、解釋
        required：引數是否必須傳
        paramType：引數放在哪個地方
            · header --> 請求引數的獲取：@RequestHeader
            · query --> 請求引數的獲取：@RequestParam
            · path（用於restful介面）--> 請求引數的獲取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：引數型別，預設String，其它值dataType="Integer"       
        defaultValue：引數的預設值

@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
        code：數字，例如400
        message：資訊，例如"請求引數沒填好"
        response：丟擲異常的類

@ApiModel：用於響應類上，表示一個返回響應資料的資訊
            （這種一般用在post建立的時候，使用@RequestBody這樣的場景，
            請求引數無法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性
     * @return
     */
    @ApiOperation(value="展示首頁資訊value", notes = "展示首頁資訊notes")
    @GetMapping("/show")
    public Object showInfo(){
        return "hello world";
    }

    @ApiOperation(value="新增使用者資訊", notes = "新增使用者資訊")
    @ApiImplicitParam(name="user", value="User", required = true, dataType = "User")
    @PostMapping("/addUser")
    public Object addUser(@RequestBody User user){
        return "success";
    }

}

遇到的一些坑

@RequestMapping(“/test”)

Api(value="/test", tags="測試介面模組")
@RestController
public class CrackController {
    @GetMapping("/test")
    public JSON crack(){
        return JsonBuilder.builder().put("validTo",Long.parseLong("111111111111111")).put("valid",true).build();
    }
    @GetMapping("/")
    public JSON index(){
        return JsonBuilder.builder().put("aaa",Long.parseLong("111111111111111")).put("valid",true).build();
    }

    @ApiOperation(value="獲取使用者列表value", notes="獲取使用者列表notes")
    @GetMapping("/{id}")
    public Object cracqk(){
        return "1342";
    }
}

上面是我剛開始寫的是沒有上面那個紅色的部分的，然後就會出現下面這個問題，啥都不顯示。

原因分析

其實主要還是自己把自己坑了，下面我的那個controller 方法寫的有問題。

 @ApiOperation(value="獲取使用者列表value", notes="獲取使用者列表notes")
    @GetMapping("/{id}")
    public Object cracqk(){
        return "1342";
    }

就是這個，他會預設把http://localhost:9998/swagger-ui.html ,後面紅色部分當做引數傳進來，導致的-，-,好了，現在問題解決了。

下一個問題

如果出現 No mapping found for HTTP request with URI [/swagger-ui.html]
解決辦法如下

@Configuration
@EnableWebMvc
public class WebMvcConfigurerConfig implements WebMvcConfigurer {
    private CorsConfiguration buildConfig() {
        CorsConfiguration corsConfiguration = new CorsConfiguration();
        corsConfiguration.addAllowedOrigin("*");
        corsConfiguration.setAllowCredentials(true);
        corsConfiguration.addAllowedHeader("*");
        corsConfiguration.addAllowedMethod("*");

        return corsConfiguration;
    }

    @Bean
    public CorsFilter corsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", buildConfig());
        return new CorsFilter(source);
    }

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

    }
}

swagger註解

swagger通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個介面
@ApiParam：單個引數描述
@ApiModel：用物件來接收引數
@ApiProperty：用物件接收引數時，描述物件的一個欄位
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的資訊
@ApiImplicitParam：一個請求引數
@ApiImplicitParams：多個請求引數