Swagger

最新推荐文章于 2024-04-12 13:58:10 发布

登楼强欲揽清辉

最新推荐文章于 2024-04-12 13:58:10 发布

阅读量410

点赞数

分类专栏： Java 文章标签： java 开发语言

本文链接：https://blog.csdn.net/cjiajiajiawa/article/details/130464265

版权

Java 专栏收录该内容

7 篇文章 0 订阅

订阅专栏

Swagger

一、Swagger简介

Swagger

号称世界上最流行的API框架
Restful Api 文档在线自动生成器实现 API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

二、Swagger使用

1、导入依赖

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2、配置Swagger

2.1、创建配置文件类

@Configuration
// 开启Swagger2的自动配置
@EnableSwagger2 
public class SwaggerConfig {

}

2.2、配置Swagger文档信息

Swagger文档信息封装于ApiInfo类，所以需要创建ApiInfo类实例对象提供Swagger文档信息

2.2.1、ApiInfo类讲解

2.2.1.1、ApiInfo类构造器及其成员变量

public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) {
    // 文档主题
    this.title = title;
    // 文档描述
    this.description = description;
    // 文档版本
    this.version = version;
    // 组织链接
    this.termsOfServiceUrl = termsOfServiceUrl;
    // 作者/联系人信息
    // 默认值为：public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
    this.contact = contact;
    // 许可
    this.license = license;
     // 许可连接
    this.licenseUrl = licenseUrl;
    // 扩展
    this.vendorExtensions = new ArrayList(vendorExtensions);
}

2.2.1.2、ApiInfo类默认实例

ApiInfo类初始化的时候就创建了一个默认的ApiInfo实例

public static final ApiInfo DEFAULT; // ApiInfo类的成员变量
static {
    DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}

这些信息会在首页展示，作为文档信息

请添加图片描述

2.2.1.3、自定义ApiInfo实例

一般情况下不会使用默认的文档信息，而是自己定义文档信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Swagger文档信息
     */
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("bloom", "花海", "1357522235@qq.com")
        return new ApiInfo(
                "接口文档",
                "学习Swagger",
                "1.0",
                "https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

2.2.2、设置文档信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Swagger的实例Docket类对象
     *
     * @return {@link Docket}
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置文档信息
                .apiInfo(apiInfo())
                .build();
    }

    /**
     * 配置Swagger文档信息
     */
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("bloom", "花海", "1357522235@qq.com");
        return new ApiInfo(
                "接口文档",
                "学习Swagger",
                "1.0",
                "https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

2.3、创建Swagger实例Docket

*2.3.1、Docket类讲解

2.3.1.1、Docket类构造器及其成员变量

public Docket(DocumentationType documentationType) {
    // 文档信息
    this.apiInfo = ApiInfo.DEFAULT;
    // 组名
    this.groupName = "default";
    // 是否开启Swagger
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    // api接口扫描器 由Docket中select方法创建的ApiSelectorBuilder建造者建造的
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

2.3.1.2、Docket构造器中DocumentationType类

在Docket类构造器中需要传入DocumentationType类对象,这个对象是表明使用Swagger文档的版本和类型，它有三个常量，这里选择SWAGGER_2

public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
    private final MediaType mediaType;
    // ...
}

2.3.1.3、Docket中的select方法（建造者模式）

当Docket对象调用select方法时会返回ApiSelectorBuilder建造者对象

public ApiSelectorBuilder select() {
    return new ApiSelectorBuilder(this);
}

这个ApiSelectorBuilder建造者需要建造三个组成部分

Docket对象
请求扫描器
路径扫描器

//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by FernFlower decompiler)
//

package springfox.documentation.spring.web.plugins;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import com.google.common.collect.Iterables;
import springfox.documentation.RequestHandler;
import springfox.documentation.spi.service.contexts.ApiSelector;

public class ApiSelectorBuilder {
    // Docket对象
    private final Docket parent;
    // 请求扫描器
    private Predicate<RequestHandler> requestHandlerSelector;
    // 路径扫描器
    private Predicate<String> pathSelector;

    public ApiSelectorBuilder(Docket parent) {
        // 若用户没有其它需求，这里会使用默认的ApiSelector.DEFAULT中提供的请求扫描器
        this.requestHandlerSelector = ApiSelector.DEFAULT.getRequestHandlerSelector();
        // 若用户没有其它需求，这里会使用默认的ApiSelector.DEFAULT中提供的路径扫描器
        this.pathSelector = ApiSelector.DEFAULT.getPathSelector();
        // return new ApiSelectorBuilder(this);
        this.parent = parent;
    }
    
    /**
    * 请求扫描器具体的建造方法
    * 用户可以根据需求建造该部分，通常是配置
    */
    public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
        this.requestHandlerSelector = Predicates.and(this.requestHandlerSelector, selector);
        return this;
    }

    public ApiSelectorBuilder paths(Predicate<String> selector) {
        this.pathSelector = Predicates.and(this.pathSelector, selector);
        return this;
    }

    public Docket build() {
        return this.parent.selector(new ApiSelector(this.combine(this.requestHandlerSelector, this.pathSelector), this.pathSelector));
    }

    private Predicate<RequestHandler> combine(Predicate<RequestHandler> requestHandlerSelector, Predicate<String> pathSelector) {
        return Predicates.and(requestHandlerSelector, this.transform(pathSelector));
    }

    private Predicate<RequestHandler> transform(final Predicate<String> pathSelector) {
        return new Predicate<RequestHandler>() {
            public boolean apply(RequestHandler input) {
                return Iterables.any(input.getPatternsCondition().getPatterns(), pathSelector);
            }
        };
    }
}

2.3.2、创建Docket对象

RequestHandlerSelectors配置要扫描接口范围

basePackage(“com.bloom.swagger.controller”) 扫描指定包下的接口
any() 扫描所有，项目中的所有接口都会被扫描到
none() 不扫描接口
withMethodAnnotation(GetMapping.class) 通过方法上的注解扫描，如只扫描get请求
withClassAnnotation(final Class<? extends Annotation> annotation) 通过类上的注解扫描，如只扫描有controller注解的类中的接口

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Swagger的实例Docket类对象
     *
     * @return {@link Docket}
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置文档信息
                .apiInfo(apiInfo())
                // 是否开启Swagger 生产环境就打开，发布时不使用
                .enable(true)
                // 扫描选择器配置 
                .select()
                // RequestHandlerSelectors配置要扫描接口范围
                // 1.basePackage("com.bloom.swagger.controller") 扫描指定包下的接口
                // 2.any() 扫描所有，项目中的所有接口都会被扫描到
                // 3.none() 不扫描接口
                // 4.withMethodAnnotation(GetMapping.class) 通过方法上的注解扫描，如只扫描get请求
                // 5.withClassAnnotation(final Class<? extends Annotation> annotation) 通过类上的注解扫描，如只扫描有controller注解的类中的接口
                .apis(RequestHandlerSelectors.basePackage("com.bloom.swagger.controller"))
                // 过滤什么路径，过滤的路径下的接口不展示
                // 1.ant() 要过滤的路径
                // 2.any()  过滤所有路径
                // 3.none() 不过滤路径
                // 4.regex() 正则表达式
                // .paths(PathSelectors.ant("/bloom/**"))
                .build();
    }

    /**
     * 配置Swagger文档信息
     */
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("bloom", "花海", "1357522235@qq.com");
        return new ApiInfo(
                "接口文档",
                "学习Swagger",
                "1.0",
                "https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

2.4、配置swagger的启用与关闭

2.4.1、在生产环境启用

2.4.1、在发布环境关闭

2.5、配置Swagger的多个分组

配置多个Docket对象就行

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("项目组一");
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("项目组二");
}

3、常用注解

3.1、@Api

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

使用方式：

@Api(value = "/user", description = "Operations about user")
public class UserController {
}

参数	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
hidden	配置为true 将在文档中隐藏

3.2、@ApiOperation

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
position	如果配置多个Api 想改变显示的顺序位置
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	响应类型（即返回对象）
responseContainer	声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”。
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	响应的HTTP状态代码。默认 200
extensions	扩展属性

3.3、@ApiParam

属性	说明
name	属性名称
value	属性值
defaultValue	默认属性值

3.4、@ApiModel

用于描述实体类

3.5、@ApiModelProperty

描述实体类属性

3.6、@ApiImplicitParam

用于标识参数

属性	说明
name	参数名
value	参数的具体意义，作用
required	参数是否必填
dataType	参数的数据类型

3.7、@ApiImplicitParams

用于标识多个参数

@PostMapping("/register")
@ApiOperation(value = "用户注册", notes = "APP用户注册")
@ApiImplicitParams({
        @ApiImplicitParam(name = "mobile", value = "手机号码", dataType = "string", paramType = "query", example = "13802780104", required = true),
        @ApiImplicitParam(name = "user_name", value = "登录账号", dataType = "string", paramType = "query", example = "lihailin9073", required = true),
        @ApiImplicitParam(name = "password", value = "登录密码", dataType = "string", paramType = "query", example = "123456", required = true),
        @ApiImplicitParam(name = "validate_code", value = "注册验证码", dataType = "string", paramType = "query", example = "3679", required = true)
})
public Object create() {
    Map<String,Object> map = new HashMap<>();
    map.put("list", null);
    return map;
}

3.8、@ApiIgnore

4、访问文档

http://localhost/swagger-ui.html

Knife4j

一、Knife4j简介

Knife4j是Swagger的增强工具

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

knife4j属于service模块公共资源，因此我们集成到service-uitl模块

二、Kinfe4j的使用

1、导入依赖

此以来整合了Swagger依赖，当导入此依赖后不需要Swagger的依赖了

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

2、配置Knife4j

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {

    /**
     * 配置Swagger的实例Docket类对象
     *
     * @return {@link Docket}
     */
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置文档信息
                .apiInfo(apiInfo())
                // 是否开启Swagger 生产环境就打开，发布时不使用
                .enable(true)
                .groupName("项目组一")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bloom.swagger.controller"))
                .build();
    }

    /**
     * 配置Swagger文档信息
     */
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("bloom", "花海", "1357522235@qq.com");
        return new ApiInfo(
                "接口文档",
                "学习Swagger",
                "1.0",
                "https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}