SpringBoot项目集成Swagger2 从0到1集成经验

不想秃头的振宇

已于 2023-03-13 10:15:26 修改

阅读量545

点赞数

于 2022-07-13 11:13:05 首次发布

本文链接：https://blog.csdn.net/qq_54196403/article/details/125759796

版权

设计时可视化
最好的 API 在设计时就考虑到了最终消费者。 Swagger Editor 和 SwaggerHub 等 Swagger 工具为 YAML 编辑器提供了一个可视化面板，供开发人员在其中工作并查看 API 对于最终消费者的外观和行为方式。
官方文档
Swagger官网

运行条件

jdk 1.8 + 否则swagger2无法运行
Maven项目

一、引入Maven依赖

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

二、添加SwaggerConfigController

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
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// 开启Swagger2的自动配置
public class SwaggerConfigController {
    @Bean
    public Docket docket() {
        // 设置要显示swagger的环境
        // 通过 enable() 接收此参数判断是否要显示
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                //.enable(false)
                // 通过.select()方法，去配置扫描接口
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.
                        // basePackage 指定要扫描的包
                        // any():扫描全部
                        // none():不扫描
                        // withClassAnnotation:扫描类上的注解，多数是一个注解的反射对象
                        // withMethodAnnotation:扫描方法上的注解
                        basePackage("com.example.demo"))
                // 配置 你想在哪个controller层生产接口文档
                //.paths(PathSelectors.ant("/search/**"))
                // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
                .build();
    }

    // 配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("wuzhenyu", "http://www.baidu.com", "zhenYu-wu@163.com");
        return new ApiInfo(
                // 标题
                "demo项目",
                // 描述
                "测试SwaggerAPI可用性",
                // 版本
                "v1.0",
                // 组织链接
                "http://www.baidu.com",
                // 联系人信息
                contact,
                // 许可
                "Apach 2.0 许可",
                // 许可连接
                "许可链接",
                // 扩展
                new ArrayList<>()
        );
    }
}

三、访问Swagger-ui

http://localhost:8080/swagger-ui.html

docket对象解析

enable()：是否启用swagger，参数为true/false，但通常用注解@Profile控制
api()：指定包扫描路径，参数形如RequestHandlerSelectors.basePackage(“com.test.api”)，也可以根据自身需求调整，其余形式参数如下
- RequestHandlerSelectors.any()：扫描所有，项目中的所有接口都会被扫描到
- RequestHandlerSelectors.none() ：不扫描接口
- RequestHandlerSelectors.withMethodAnnotation(final Class<? extends Annotation> annotation)，
  通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
- RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> annotation)，
  通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
- RequestHandlerSelectors.basePackage(final String basePackage) ：根据包路径扫描接口
paths()：指定url路径过滤，参数形如PathSelectors.ant(“/login/**”)，也可以根据自身需求调整，其余形式参数如下
- PathSelectors.any()：任何请求都扫描
- PathSelectors.none() ：任何请求都不扫描
- PathSelectors.regex(final String pathRegex) ：通过正则表达式控制
- PathSelectors.ant(final String antPattern) ：通过ant()控制
groupName()：配置分组，参数为String字符串，如group 1，默认分组为default，如需设置多个分组，则实例化多个不同名的docket即可

涉及注解解析

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：返回码，例如400
- message：信息，例如"参数错误"
- response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
@ApiIgnore：忽略某个api，可用于单个接口，也可用于整个controller

接口使用注解

	@ApiOperation("测试swagger")
    @PostMapping("/testSwagger")
    @ResponseBody
    public voidtestSwagger(@ApiParam(required = false, value = "登录实体") @RequestParam(required = false) 	@RequestBody LoginRequest loginRequest) throws Exception {
    }

@ApiParam

以下按照属性名称数据类型默认值说明

name String “” 参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
value String “” 参数简单描述
defaultValue String “” 描述参数默认值
allowableValues String “” 可接收参数值限制，有三种方式,取值列表，取值范围
required boolean false 是否为必传参数, false:非必传; true:必传
access String “” 参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
allowMultiple boolean false 指定参数是否可以通过多次出现来接收多个值
hidden boolean false 隐藏参数列表中的参数
example String “” 非请求体(body)类型的单个参数示例
examples Example @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求
type String “” 添加覆盖检测到类型的功能
format String “” 添加提供自定义format格式的功能
allowEmptyValue boolean false 添加将格式设置为空的功能
readOnly boolean false 添加被指定为只读的能力
collectionFormat String “” 添加使用 array 类型覆盖 collectionFormat 的功能