Swagger2框架

moran
2021-02-18 / 0 评论 / 8 阅读 / 正在检测是否收录...
温馨提示:
本文最后更新于2021年04月14日,已超过72天没有更新,若内容或图片失效,请留言反馈。

Swagger2框架

在前后端分离的项目中,后端负责控制器和模型,但是前端对接后端的接口需要有接口文档,接口文档用来描述接口的信息。因此,Swagger可以通过注解自动生成接口文档。

OpenAPI

Swagger简介


Springfox

简单例子

  • pom
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.bjsxt</groupId>
    <artifactId>swagger</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>2.4.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
    </dependencies>
</project>
  • 启动类
    package com.bjsxt;

    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;

    /**
     * EnableSwagger2 是Springfox提供的一个注解,代表swagger2相关技术的开启
     * 会扫描当前类所在包及子包下的所有的类型的注解。做Swagger文档的定制
     */
    @EnableSwagger2
    @SpringBootApplication
    public class MyApp {

        public static void main(String[] args) {
            SpringApplication.run(MyApp.class,args);
        }
    }
  • 控制器
    package com.bjsxt.controller;

    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;

    @RestController
    public class MyController {

        @PostMapping("/post")
        public String post(){
            return "post";
        }

        @GetMapping("/get")
        public String get(String a,String b){
            return "get";
        }

        @RequestMapping("/req")
        public String req(String m){
            return "req";
        }
    }

启动后,访问http://localhost:8080/swagger-ui/进入接口文档首页

basic-error-controller是springboot提供的异常跳转的接口。
MyController是自己定义的接口。

会发现通过@RequestMapping标注的接口会产生所有类型的文档。因为@RequestMapping没有标注请求类型。


还可以通过右上角的try it out测试接口

Swagger配置

上述例子中的接口文档中标题部分可以通过代码自定义。

  • 配置头部标题部分
    package com.bjsxt.config;

    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;

    @Configuration
    public class SwaggerConfig {

        /**
         * 创建Docket对象, 并交给spring管理
         * Docket 是Swagger中的全局配置对象
         * @return
         */
        @Bean
        public Docket docket(){
            // 通过全局配置对象创建swagger2的文档类型
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            // ApiInfo-api文档帮助的描述信息 information
            ApiInfo apiInfo = new ApiInfoBuilder()
                                    .contact( // 配置swagger文档头部内容
                                                new Contact(
                                                        "Swagger学习文档",      // 文档发布者名称
                                                        "http://www.baidu.com",  // 文档发布者企业网址
                                                        "[email protected]")    // 文档发布者邮箱
                                        )
                                        .title("Swagger学习文档")   // 文档标题
                                        .description("Swagger框架学习帮助文档")    // 文档描述
                                        .version("1.1") // 文档版本
                                        .build();
                // 给docket上下文配置api描述信息
                docket.apiInfo(apiInfo);

                return docket;
            }
        }

通过上述代码配置后显示如下图:

  • 配置扫描包
 docket
                // 获取Docket中的选择器,返回ApiSelectorBuilder。构建选择器的。作用如:配置扫描什么包下的注解
                .select()
                // 配置扫描的规则,设定扫描哪个包及子包中的注解。
                .apis(RequestHandlerSelectors.basePackage("com.bjsxt.controller"))
                .build();

再配置后需要通过build重新构建docket对象
配置后如下图显示:

base-error-controller就不被扫描到,只剩下自己的controller了。

  • 通过自定义注解不扫描被注解的方法

    • 自定义注解类
    package com.bjsxt.anno;
    
    import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    
    /**
     * @Target  - 描述当前的注解可以定义在什么资源上
     *  属性 value
     *     - 定义具体的资源,包括:
     *      - ElementType.METHOD 可以定义在方法上
     *      - ElementType.TYPE 可以定义在类型上
     *      - ElementType.FIELD 可以定义在属性上
     *      - ElementTYpe.PARAMETER 可以定义在方法参数上
     * @Retention - 当前注解在什么时候生效
     *  属性  value
     *      - 定义具体的生效时间
     *          - RetentionPolicy.RUNTIME 运行时有效
     *          - RetentionPolicy.SOURCE  源码中有效
     *          - RetentionPolicy.CLASS   字节码有效
     */
    @Target(value={ElementType.METHOD,ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyAnnotationSwagger {
    
        // 自定义注解的属性,相当于@MyAnnotationSwagger(value="")
        String value()  default "";
    }
    
    • 控制器方法
    @MyAnnotationSwagger
    @RequestMapping("/req")
    public String req(String m){
        return "req";
    }
    • 配置类
    package com.bjsxt.config;
    
    import com.bjsxt.anno.MyAnnotationSwagger;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    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;
    
    @Configuration
    public class SwaggerConfig {
    
        /**
         * 创建Docket对象, 并交给spring管理
         * Docket 是Swagger中的全局配置对象
         * @return
         */
        @Bean
        public Docket docket(){
            // 通过全局配置对象创建swagger2的文档类型
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            // ApiInfo-api文档帮助的描述信息 information
            ApiInfo apiInfo = new ApiInfoBuilder()
                                    .contact( // 配置swagger文档头部内容
                                            new Contact(
                                                    "Swagger学习文档",      // 文档发布者名称
                                                    "http://www.baidu.com",  // 文档发布者企业网址
                                                    "[email protected]")    // 文档发布者邮箱
                                    )
                                    .title("Swagger学习文档")   // 文档标题
                                    .description("Swagger框架学习帮助 文档")    // 文档描述
                                    .version("1.1") // 文档版本
                                    .build();
            // 给docket上下文配置api描述信息
            docket.apiInfo(apiInfo);
    
            docket
                // 获取Docket中的选择器,返回ApiSelectorBuilder。构建选择器的。作用如:配置扫描什么包下的注解
                .select()
                .apis(
                        // lamabda表达式,取反,不包含该注解
                        requestHandler -> !requestHandler.isAnnotatedWith(MyAnnotationSwagger.class)
                )
                // 配置扫描的规则,设定扫描哪个包及子包中的注解。
                .apis(RequestHandlerSelectors.basePackage("com.bjsxt.controller"))
                .build();
    
            return docket;
        }
    }

    通过上述代码后只会扫描被注解的方法

  • 指定路径生成文档
    docket
                    // 获取Docket中的选择器,返回ApiSelectorBuilder。构建选择器的。作用如:配置扫描什么包下的注解
                    .select()
                    .apis(
                            // lamabda表达式,取反,不包含该注解
                            requestHandler -> !requestHandler.isAnnotatedWith(MyAnnotationSwagger.class)
                    )
                    // 配置扫描的规则,设定扫描哪个包及子包中的注解。
                    .apis(RequestHandlerSelectors.basePackage("com.bjsxt.controller"))
                    // 指定路径生成api文档
                    .paths(
                            // 使用正则表达式约束生成api文档的路径
                           PathSelectors.regex("/swagger/.*")
                    )
                    .build();

结果:

swagger常用注解

@Api

用于描述控制器的信息

  • 简单例子
@RestController
@RequestMapping("/swagger")
@Api(tags = {"MyController","学习使用Swagger"},description = "测试Api")
public class MyController {
  • 结果
加在类上
多个tag就会生成多个名称不同但内容一致的控制器。
description是控制器的描述信息,已过时。

@ApiOperation

用于描述方法的信息

  • 简单例子
 @PostMapping("/post")
    @ApiOperation(value="post方法,执行数据新增",notes = "swagger学习使用-处理post请求的方法")
    public String post(){
        return "post";
    }
  • 结果
可以加在方法和类上,常用于方法上
value不能为空,相当于简短描述
而notes相当于详细描述

@ApiParam

用于描述方法参数的信息

  • 简单例子
@GetMapping("/get")
    public String get(
            @ApiParam(name="用户名",value="新增用户时提供的用户名",required = true) String a,
            @ApiParam(name="密码",value="新增用户时提供的密码",required = true) String b){
        return "get";
    }
  • 结果
可以加在方法参数,方法,字段上,通常加在参数上
不推荐使用属性,因为参数名称被替代了。
这里只举例了两个属性,其他属性可以进入该注解查看。

@ApiModel和@ApiModelProperty

用来描述实体类型

  • 简单例子
    package com.bjsxt.entity;

    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;

    import java.io.Serializable;
    import java.util.Objects;

    /**
     * ApiModel注解用于描述实体类型,当该实体类型成为接口返回类型时会被解析
     */
    @ApiModel(value="自定义实体-MyEntity",description = "MyEntity存储用户数据")
    public class MyEntity implements Serializable {

        @ApiModelProperty(value="主键",name="主键(id)",required = true,example = "1",hidden = false)
        private String id;
        @ApiModelProperty(value="姓名",name="姓名(name)",required = true,example = "张三",hidden = false)
        private String name;
        @ApiModelProperty(value="密码",name="密码(password)",required = true,example = "123456",hidden = false)
        private String password;

        public MyEntity(){}

        @Override
        public boolean equals(Object o) {
            if (this == o) return true;
            if (o == null || getClass() != o.getClass()) return false;
            MyEntity myEntity = (MyEntity) o;
            return Objects.equals(id, myEntity.id) &&
                    Objects.equals(name, myEntity.name) &&
                    Objects.equals(password, myEntity.password);
        }

        @Override
        public int hashCode() {
            return Objects.hash(id, name, password);
        }

        @Override
        public String toString() {
            return "MyEntity{" +
                    "id='" + id + '\'' +
                    ", name='" + name + '\'' +
                    ", password='" + password + '\'' +
                    '}';
        }

        public String getId() {
            return id;
        }

        public void setId(String id) {
            this.id = id;
        }

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }

        public String getPassword() {
            return password;
        }

        public void setPassword(String password) {
            this.password = password;
        }
    }
  • 结果

注解@ApiModel标注在实体类上,用于描述实体类
注解@APiModelProperty标注在实体类属性上,用于描述属性

@ApiIgnore

用于忽略被标注该注解的资源不成才api文档

  • 简单例子
@ApiIgnore
    @RequestMapping("/req")
    public String req(String m){
        return "req";
    }
  • 结果
可以加在方法,类,参数上。通常使用在方法上。
和之前自定义的注解`@MyAnnotationSwagger`的作用类似。

@ApiImplIcitParam

用来描述方法参数

  • 简单例子
@GetMapping("/test")
    @ApiImplicitParam(name="m",value="m参数的描述",required = false,paramType = "query",dataType = "名值对")
    public String test(String m,String n){
        return "test";
    }
  • 结果

该注解只能加在方法上
作用和@ApiParam类似,通过@ApiImplicitParams可以描述多个参数,不同的是前者在参数行内注解,而后者在方法上注解。

Swagger2 3.0更新

  • 新增starter
    在旧版本swagger2.x中,引入swagger-ui和swagger2,新版本可以引入starter

(案例中引入的就是starter)

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
  • 新增注解@EnableOpenApi
    新版本不再推荐使用注解@EnableSwagger2,而是使用@EnableOpenApi来开启注解功能。
  • 移除依赖
    新版本移除guava依赖
0

评论 (0)

取消