springboot2.1.7整合swagger2.9.2

什么是swagger？

swagger是用於定義API文檔的一個框架。

為什么要使用swagger?

當下項目開發時前后端是分離的，那么接口就成了前后端唯一的紐帶。前端工程師如何知道哪個接口是干嘛的？里面有什么方法？方法需要什么參數？...... 這時候就需要一份簡潔且詳盡API文檔，swagger就是用來自動生成API文檔。

怎么使用swagger?

1. 導入pom依賴

不同的版本ui界面有所差別，個人感覺2.7.0比較舒服

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

2. 編寫配置類（復制可直接使用，最好建一個config包放以下類）

SwaggerConfig類：

@Configuration  //聲明這是一個注解類
@EnableSwagger2

public class SwaggerConfig {

    @Bean
    public Docket customDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors
                .basePackage("com.gl.pin.web.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("zjk",
                "https://www.cnblogs.com/zjk-main/",
                "[e-mail]");
        return new ApiInfoBuilder()
                .title("項目API接口")
                .description("接口描述")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

WebMvcConfig類：

@Configuration
@EnableWebMvc
public class WebMvcConfig implements WebMvcConfigurer {
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        // 解決靜態資源無法訪問（可選）
        /*registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");*/
        // 直接在瀏覽器訪問：根目錄/swagger-ui.html
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 需要用到的webjars（包含js、css等）
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3. 在每個controller、method上加上注釋

@Api加在類上

@ApiOperation加在方法上

示例：

@ResponseBody
@Controller
@RequestMapping(value = "/admin")
@Api(value = "沒什么用，可不配",tags = "admin/zjk",description = "管理員操作")
public class AdminController {

    @ApiOperation(httpMethod = "POST",value = "管理員登錄" ,produces = MediaType.TEXT_HTML_VALUE,tags = "admin/zjk",notes = "參數")
    @PostMapping(value = "/login")
    public String login(AdminEntity adminEntity){
         return "login";
    }
}

4. 訪問根目錄/swagger-ui.html

在這個頁面可以看到controller類的描述，類里面方法的描述，方法參數、返回值的描述等等。swagger還提供了類似於postman的接口測試功能。