spring boot整合swagger详解

spring boot整合swagger详解

一、步骤

1、导包

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

说明：springfox-swagger2包是swagger整合的核心包，包含了各个注解，导入该包解决注解报错问题，springfox-swagger-ui包是ui基础包，要访问swagger-ui.html需要导入

2、编写配置文件

创建一个swagger的配置类，名字随意，推荐SwaggerConfig，且注册一个Docket的bean，以便springboot能过够将swagger的配置加载

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docker(){
        // 构造函数传入初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                .apiInfo(apiInfo())
                .groupName("yichun123")
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                .enable(true)
                .select()
                //apis： 添加过滤条件,
                .apis(RequestHandlerSelectors.basePackage("com.landa.gzdzll.controller"))
                //paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/user以外的其它路径都会生成api文档
                .paths((String a) ->
                        !a.equals("/user"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("名字：lvgang", "个人链接：", "邮箱：753405");
        return new ApiInfo(
                "工装电子领料系统Api", // 标题
                "描述内容", // 描述
                "版本内容：v1.0", // 版本
                "链接：http://terms.service.url/", // 组织链接
                contact, // 联系人信息
                "许可：Apach 2.0 ", // 许可
                "许可链接：XXX", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

3、配置完成

配置完成后，启动项目，访问http://localhost:8080/swagger-ui.html，可以看到

二、可能出现的问题

我在配置过程中出现启动项目后无法访问swagger-ui.html页面的问题，此问题在于yml配置的扫描资源包下不存在该页面，此页面是在依赖包下的，所以想要访问到该页面，需要重写addResourceHandlers方法，这是配置spring视图解析的方法，有两种修改方式：

方式一：

实现WebMvcConfigurer接口，实现addResourceHandlers，此方式不会覆盖yml文件里的配置，只会额外的进行资源配置，配置完成后不影响你自己写的访问路径和编码格式（此处加粗的地方是我遇到的坑）

方式二：

继承WebMvcConfigurationSupport类，重写addResourceHandlers方法，此方法会覆盖yml文件里的配置，只使用addResourceHandlers方法中指定的资源配置，存在编码格式问题

方式三：

直接在yml文件中写资源配置，此方法会影响其他正常的访问路径

下面是我写的代码：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class PathConfig implements WebMvcConfigurer {

	// 统一路径管理，进行页面跳转的路径管理，其他方法的路径管理写在各自的类中
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/login").setViewName("/login");
        registry.addViewController("/index").setViewName("/index");
    }

    @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常用注解

1. @Api 用于类，说明该类的作用。可以标记一个Controller类做为swagger 文档资源

tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

2. @ApiOperation() 用于方法；表示一个http请求的操作

value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

3.@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

name–参数名
value–参数说明
required–是否必填

4.@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收

value–表示对象名
description–描述
都可省略

5.@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改

value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

6.@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上

7.@ApiImplicitParam() 用于方法

8.@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型

四、注解补充

@RequestParam注解 或 @RequestBody

@ApiParam()注解标识的参数，需要搭配@RequestParam 或 @RequestBody使用才能在swagger-ui.html页面上输入参数值，并返回，否则不能输入参数值，不方便测试接口
随便说一下，根据请求头，决定@requestBody使用的场景：
application/x-www-form-urlencoded， 可选（即非必须，因为这种情况的数据@RequestParam, @ModelAttribute也可以处理，当然@RequestBody也能处理）；
multipart/form-data, 不能处理（即使用@RequestBody不能处理这种格式的数据）；
其他格式， 必须（其他格式包括application/json, application/xml等。这些格式的数据，必须使用@RequestBody来处理）。

例如：

不使用@RequestParam 或 @RequestBody时

使用@RequestParam 或 @RequestBody时

暂时还没有弄明白为什么需要搭配。

希望能帮助到各位！！！！！

奥~~ 还有一点，最近我的堂妹高考完填报志愿，问我来着，我发现一个奇怪的现象，越来越多的人涌入计算机行业，都奔着高薪来的，我就想说，计算机是高薪，但也有一定的局限性，有的人再怎么努力也无法突破技术瓶颈，想往底层去抠代码堪比便秘一样难受，你来计算机行业干啥，所谓360行，行行出状元，别整天就想着奔高薪去，我们现在流的泪都是当时脑子进的水，奉劝各位后生，认真考虑清楚，国家还有很多东西需要人，别只想着高薪，或许你不是这块料。

助所有码农们，码到成功。