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/",

                "1066406756@qq.com");

        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的接口测试功能。

巴特西