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/",
                "[email protected]");
        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的接口测试功能。