学习笔记

发布日期: 2020-10-03

更新日期: 2021-01-18

文章字数: 2.1k

阅读时长: 9 分

阅读次数:

Swagger2.

官网：https://swagger.io/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

号称世界上最流行的API框架
RestFul API文档在线自动生成工具=> API文档与API定义同步更新
直接运行，可以在线测试API接口
支持多种语言：Java、php 。。。

优点：

大大减少前后端的沟通
方便查找和测试接口
提高团队的开发效率
方便新人了解项目

SpringBoot集成Swagger.

1、导入依赖.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.10.5</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.10.5</version>
</dependency>

2、创建一个HelloController.

@Controller
public class HelloController {
    @RequestMapping("/hello")
    @ResponseBody
    public String hello(){
        return "hello";
    }
}

3、创建SwaggerConfig.

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

}

4、访问`localhost:8080/swagger-ui.html`.

配置Swagger.

基本信息apiInfo.

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

    // 配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //基本信息
                .apiInfo(apiInfo());
    }

    // 配置Swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("liuyou-website", "http://www.liuminkai.top", "111@qq.com"); // 作者信息
        return new ApiInfo(
                "xxx的Swagger信息标题", // 标题
                "详细描述", // 描述
                "1.0", // 版本
                "urn:tos", // 所属组 的 urn 
                 contact, // 作者信息
                "Apache 2.0", // 许可证
                "http://www.apache.org/licenses/LICENSE-2.0", // 许可证url
                new ArrayList()
        );
    }
}

配置接口扫描.

public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        // 配置接口扫描
        .select()
        /*
            apis:
                RequestHandlerSelectors 配置扫描接口的方式
                    basePackage(): 按指定包扫描api接口
                    any(): 扫描全部
                    none(): 不扫描
                    withMethodAnnotation(): 扫描方法上的带指定注解的api接口， 如@GetMapping修饰方法
                    withClassAnnotation(): 扫描类上的带指定注解的类上的api接口，如@RestController修饰类下所有的api接口
        */
        .apis(RequestHandlerSelectors.basePackage("com.liuyou.controller"))
        /*
            paths:
                PathSelectors 路径筛选 -- 这里是url请求路径
                    ant(): ant pattern 筛选url路径
                    none(): 不筛选 -- 不会匹配 任何url路径  导致 No operations defined in spec!
                    any(): 筛选所有 -- 所有url路径
                    regex(): 正则表达式

                    一般用 apis 中 的 basePackage 就够了
        */
//        .paths(PathSelectors.none())
        .build();
}

配置是否启动Swagger.

public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .enable(false);// false:关闭
}

一般，我们希望Swagger在生成环境中使用，在发布时不使用

假如我们项目有多个配置文件：
- application.properties – spring.profiles.active= 激活环境
- application-dev.properties
- application-prod.properties

public Docket docket(Environment environment){// 添加参数
    // 设置要显示的 Swagger 环境 -- 当然可以使用 注解代替
    Profiles profiles = Profiles.of("dev", "test");// 希望测试环境 和 开发环境 显示
    boolean flag = environment.acceptsProfiles(profiles);// 会会检测当前环境是否是 以上环境 是返回true，否则返回false

    return new Docket(DocumentationType.SWAGGER_2)
        .enable(false);// false:关闭
}

配置分组.

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("group1");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("group2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("group3");
}

Swagger注解.

参考自：https://zhuanlan.zhihu.com/p/49996147

`@Api`.

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

`@ApiOperation`.

用于方法，表示一个http请求访问该方法的操作

参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

`@ApiModel`.

用于响应实体类上，用于说明实体作用

参数：

description="描述实体的作用"

`@ApiModelProperty`.

用在属性上，描述实体类的属性

参数：

value="用户名"  描述参数的意义
name="name"    参数的变量名
required=true     参数是否必选

`@ApiImplicitParams`.

用在请求的方法上，包含多@ApiImplicitParam

`@ApiImplicitParam`.

用于方法，表示单独的请求参数

参数：

name="参数名" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

`@ApiParam`.

用于方法，参数，字段说明表示对参数的要求和说明

参数：

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false

`@ApiResponses`.

用于请求的方法上，根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

`@ApiResponse`.

用在请求的方法上，表示不同的响应

参数：

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"

`@ApiIgnore`.

用于类或者方法上，不被显示在页面上

`@Profile({"dev", "test"})`.

用于配置类上，表示只对开发和测试环境有用

完整示例.

实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("User实体类")
public class User implements Serializable {
    private static final long serialVersionUID = 5978016955197106792L;
    @ApiModelProperty(value = "账号",name = "username")
    private String username;
    @ApiModelProperty(value = "密码", name = "password")
    private String password;
}

请求类

@RestController
@Api(value = "hello控制类",tags = {"类的作用：接收请求，跳转页面"})
public class HelloController {
    @RequestMapping("/hello")
    @ApiOperation(value = "接收hello，跳转到hello.html", notes = "注意：请求方法不做要求")
    public String hello(@ApiParam(name = "id",value = "ID")Integer id){
        return "hello";
    }

    // 只要我们的接口中，返回值中存在实体类，它就会被扫描到Swagger中
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "String"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "String")
    })
//    @ApiResponse()
    @RequestMapping("/user")
    public User user(String username, String password){
        return new User();
    }
}

结果展示

补充.

SwaggerConfig 合集.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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 SwaggerConfig {

    // 配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){

        // 设置要显示的 Swagger 环境 -- 当然可以使用 注解代替
        Profiles profiles = Profiles.of("dev", "test");// 希望测试环境 和 开发环境 显示
        boolean flag = environment.acceptsProfiles(profiles);// 会会检测当前环境是否是 以上环境 是返回true，否则返回false


        return new Docket(DocumentationType.SWAGGER_2)
            //基本信息
            .apiInfo(apiInfo())
            // 配置接口扫描
            .select()
            /*
                apis:
                    RequestHandlerSelectors 配置扫描接口的方式
                        basePackage(): 按指定包扫描api接口
                            any(): 扫描全部
                            none(): 不扫描
                            withMethodAnnotation(): 扫描方法上的带指定注解的api接口， 如@GetMapping修饰方法
                        withClassAnnotation(): 扫描类上的带指定注解的类上的api接口，如@RestController修饰类下所有的api接口
            */
            .apis(RequestHandlerSelectors.basePackage("com.liuyou.controller"))
            /*
                paths:
                    PathSelectors 路径筛选 -- 这里是url请求路径
                        ant(): ant pattern 筛选url路径
                        none(): 不筛选 -- 不会匹配 任何url路径  导致 No operations defined in spec!
                        any(): 筛选所有 -- 所有url路径
                        regex(): 正则表达式

                        一般用 apis 中 的 basePackage 就够了
                */
//              .paths(PathSelectors.none())
            .build()
            .enable(flag); //true 启动 | false 关闭
    }

    // 配置Swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("liuyou-website", "http://www.liuminkai.top", "111@qq.com"); // 作者信息
        return new ApiInfo(
                "xxx的Swagger信息标题", // 标题
                "详细描述", // 描述
                "1.0", // 版本
                "urn:tos", // 所属组 的 urn
                 contact, // 作者信息
                "Apache 2.0", // 许可证
                "http://www.apache.org/licenses/LICENSE-2.0", // 许可证url
                new ArrayList()
        );
    }
}

注意.

2.10.5版本变化.

1、依赖变化.

以前是两个，现在是三个

webmvc与webflux对比：https://blog.csdn.net/weixin_33893473/article/details/88020932

webmvc

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.10.5</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.10.5</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-spring-webmvc</artifactId>
    <version>2.10.5</version>
</dependency>

webflux

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.10.5</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.10.5</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-spring-webmvc</artifactId>
    <version>2.10.5</version>
</dependency>

2、注解变化.

去除了原来的 @EnableSwagger2，引入 @EnableSwagger2WebMvc， @EnableSwagger2WebFlux

如果没有引入对应依赖可能会出现如下情况

新版界面

liuminkai

http://www.liuminkai.top/2020/10/03/36126.html

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 liuminkai !

Swagger springboot

springboot上使用devtools热部署

springboot上使用devtools热部署.步骤.1、引入依赖.devtools <dependency> <groupId>org.springframework.boot</groupId> &l

2020-10-04 学习笔记

springboot 热部署 devtools

javase -- Array和List之间的转换

本文出自：https://blog.csdn.net/qq_41097354/article/details/90403953 数组转List.package listtoArray; import java.util.ArrayLi

2020-10-03 转载

javase

springBoot学习笔记-19-Swagger

Swagger2.

SpringBoot集成Swagger.

1、导入依赖.

2、创建一个HelloController.

3、创建SwaggerConfig.

4、访问localhost:8080/swagger-ui.html.

配置Swagger.

基本信息apiInfo.

配置接口扫描.

配置是否启动Swagger.

配置分组.

Swagger注解.

@Api.

@ApiOperation.

@ApiModel.

@ApiModelProperty.

@ApiImplicitParams.

@ApiImplicitParam.

@ApiParam.

@ApiResponses.

@ApiResponse.

@ApiIgnore.

@Profile({"dev", "test"}).

完整示例.

补充.

SwaggerConfig 合集.

注意.

2.10.5版本变化.

1、依赖变化.

2、注解变化.

4、访问`localhost:8080/swagger-ui.html`.

`@Api`.

`@ApiOperation`.

`@ApiModel`.

`@ApiModelProperty`.

`@ApiImplicitParams`.

`@ApiImplicitParam`.

`@ApiParam`.

`@ApiResponses`.

`@ApiResponse`.

`@ApiIgnore`.

`@Profile({"dev", "test"})`.