Swagger学习记录

最新推荐文章于 2024-10-02 15:19:42 发布

lilesien

最新推荐文章于 2024-10-02 15:19:42 发布

阅读量558

点赞数

分类专栏：计算机笔记文章标签： spring boot java Swagger

本文链接：https://blog.csdn.net/m0_48847163/article/details/121343522

版权

计算机笔记专栏收录该内容

32 篇文章 0 订阅

订阅专栏

Swagger

Swagger简介

官网：https://swagger.io/

在项目中使用swagger需要springfox

swagger2
swaggerui

Springboot继承Swagger

新建一个springboot-web项目

导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<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>

编写一个工程，编写swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

测试，输入http://localhost:8080/swagger-ui.html查看swagger-ui界面

配置Docket

swagger的bean实例Docket，我们可以自己配置Docket来改变swagger-ui界面，在Docket中都有对应的属性来改变

@Configuration
@EnableSwagger2//开启Swagger
public class SwaggerConfig {

    //配置swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    public ApiInfo apiInfo(){
        //Contact传入个人信息:姓名,个人网站，个人邮箱
        Contact contact = new Contact("***","#","************@qq.com");
        return new ApiInfo("标题",
                        "文本描述",
                        "1.0", "urn:tos",
                        contact,
                        "Apache 2.0",
                        "http://www.apache.org/licenses/LICENSE-2.0",
                        new ArrayList());
    }
    
}

Docket实现了DocumentationPlugin（文本插件）接口，Docket的构造方法需要传入一个DocumentationType类型的参数，可以直接通过DocumentationType.静态成员变量进行传值。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-yIjdTN0W-1636981598473)(C:/Users/26794/AppData/Roaming/Typora/typora-user-images/image-20211111112016419.png)]

创建完对象后调用apiInfo返回Docket的Bean实例。apiInfo()需要传入ApiInfo实例，在swaggerConfig中编写一个apiInfo方法，放入Docket的apiInfo方法中。

ApiInfo的默认值是:

public static final Contact DEFAULT_CONTACT = new Contact("", "", "");

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());
    }

//DEFAULT_CONTACT是一个Contact类型的常量，我们可以传入我们自己定义的Contact

我们可以（只能）通过构造方法对我们需要改变的值进行改变。每个属性对应我们swagger-ui界面的一部分。

Swagger配置扫描接口

配置Swagger的扫描接口，需要用到Swagger的Docket类，所以我们需要在创建Docket Bean实例的时候，就进行配置：

在上面的方法中进行修改

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                //apis  配置扫描接口
                //RequestHandlerSelectors, 配置要扫描接口的方式
                //basePackage   指定扫描的包
                //any 扫描全部
                //none 不扫描
                //withClassAnnotation 扫描类上的注解        传入参数为注解的class对象
                //withMethodAnnotation 扫描方法上的注解         传入参数为注解的class对象
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //path过滤，表示过滤什么路径将其呈现在页面上(url路径)
                .paths(PathSelectors.ant("/"))
                .build();
    }

配置是否启动Swagger：

在Docket中有一个属性enabled，默认值为true，表示Swagger是默认启动的，我们可以对将enbale赋值为false，默认Swagger不启动。

根据这个特性，我们可以在启动Swagger之前对所需要准备的条件进行判断，如果条件都符合，则可以在浏览器中访问Swagger，否则就表示不能访问Swagger。

比如说只允许Swagger在dev环境中使用，在发布的时候不能使用。我们所需的操作就是在将Docket实例添加到Spring容器中前对环境进行判断。

这里就需要我们SpringBoot的多环境配置：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-S3BZZs18-1636981598477)(C:/Users/26794/AppData/Roaming/Typora/typora-user-images/image-20211115195915344.png)]

    @Bean
    public Docket docket(Environment environment){

        //设置Swagger要在什么环境下启动
        Profiles profiles = Profiles.of("dev");

        //监听环境，如果Swagger环境不在profiles中，则返回false，最后传递给enable属性
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(flag)
                .select()
                //apis  配置扫描接口
                //RequestHandlerSelectors, 配置要扫描接口的方式
                //basePackage   指定扫描的包
                //any 扫描全部
                //none 不扫描
                //withClassAnnotation 扫描类上的注解        传入参数为注解的class对象
                //withMethodAnnotation 扫描方法上的注解         传入参数为注解的class对象
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //path过滤，表示过滤什么路径将其呈现在页面上
                .paths(PathSelectors.ant("/"))
                .build();
    }

要进行监听环境不只有这一种方法，我们也可以通过读取properties文件对环境进行判断。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-a8ntY4N9-1636981598480)(C:/Users/26794/AppData/Roaming/Typora/typora-user-images/image-20211115200048761.png)]

注意：当环境进行改变后，浏览器中的端口号也要进行改变。

分组开发

想要实现分组开发，只需要配置多个Docket即可。

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

实体类配置

我们可以通过@Api***等一系列注释对我们实体类中的字段以及实体类的作用进行配置

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

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

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

当然，我们也可以使用Api一些列注解对我们的controller类进行配置，比如：

@RestController
public class HelloController {

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

    @ApiOperation("用户post请求测试")
    @PostMapping("/userPet")
    public User user(){
        return new User();
    }

    @ApiOperation("用户get请求测试")
    @GetMapping("/userPost")
    public User user1(User user){
        return user;
    }

}