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,可以看到
spring boot整合swagger详解

二、可能出现的问题

我在配置过程中出现启动项目后无法访问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页面上输入参数值,并返回,否则不能输入参数值,不方便测试接口

例如:

不使用@RequestParam 或 @RequestBody时
spring boot整合swagger详解
使用@RequestParam 或 @RequestBody时
spring boot整合swagger详解
暂时还没有弄明白为什么需要搭配。

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

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

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

上一篇:SpringBoot 集成Swagger2自动生成文档和导出成静态文件


下一篇:Swagger食用方法详解