Swagger笔记

最新推荐文章于 2022-09-15 21:19:50 发布

sun-flower__

最新推荐文章于 2022-09-15 21:19:50 发布

阅读量872

点赞数 2

分类专栏：微服务文章标签： java restful spring

本文链接：https://blog.csdn.net/L__HH/article/details/122550972

版权

微服务专栏收录该内容

4 篇文章 0 订阅

订阅专栏

Swagger笔记

1、Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

支持在线同步API文档，不用手动编写API文档。
支持Web页面的在线测试API，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

swagger官网：https://swagger.io/

2、Swagger使用步骤

导入依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
</dependency>

配置swagger

@Configuration
@EnableSwagger2  // 开启swagger
public class SwaggerConfig {
    
    // 这样就可以使用swagger的默认配置 
}

测试：访问localhost:8080/swagger-ui.html就可以访问默认的页面

3、Swagger配置信息

// 配置Docket的相关信息
@Bean
public Docket getDocket(){


    // 文档类型设置为DocumentationType.SWAGGER_2
    return new Docket(DocumentationType.SWAGGER_2)
            // 设置对应的swagger的api信息，参数是一个Contact对象
            // 默认是ApiInfo实体类
            .apiInfo(this.getApiInfo());
}
/*
 默认的信息
 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());
 }
 */
private ApiInfo getApiInfo(){
    // 文档的作者信息
    Contact contact = new Contact("xiaotanke", "http://www.yujiangg.com", "LHJ160414@163.com");
    return new ApiInfo(
            // 题目
            "测试的Swagger文档",
            // 描述
            "这是一个测试api文档",
            // 版本
            "v-1.0",
            // 作者网站
            "http://www.yujiangg.com",
            // 作者的个人信息
            contact,
            // 开源信息
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
    );
}

4、Swagger配置扫描

swagger默认是扫描项目的全部接口，即扫描项目中的所有controller中的接口，但是我们可以自定义扫描接口。

// 配置Docket的相关信息
    @Bean
    public Docket getDocket(){


        // 文档类型设置为DocumentationType.SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                // 设置对应的swagger的api信息，参数是一个Contact对象
                // 默认是ApiInfo实体类
                .apiInfo(this.getApiInfo())
                // 自定义扫描接口，select()和build()是联合使用的，只能在之间配置
                // 两种方式，选择一种
                .select()
                // apis配置扫描接口范围
                /*
                    basePackage(): 扫描指定包下的接口
                    any(): 全部扫描，默认全部扫描
                    none(): 全都不扫描
                    withMethodAnnotation(): 扫描方法上有指定注解的接口，参数是指定注解的class对象
                    RequestHandlerSelectors(): 扫描类上有指定注解的接口，参数是指定注解的class对象
                 */
//                .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
                .apis(RequestHandlerSelectors.any())
//                .apis(RequestHandlerSelectors.none())
//                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
//                .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                // 扫描过滤请求下的接口
                /*
                    ant(): 添加一个过滤请求，扫描这下面的接口
                    any(): 全部扫描
                    none(): 全都不扫描
                    regex(): 扫描满足指定正则的接口
                 */
//                .paths(PathSelectors.ant("/admin/**"))
//                .paths(PathSelectors.any())
//                .paths(PathSelectors.none())
                .paths(PathSelectors.regex("正则字符串"))
                .build();
    }

5、Swagger其他配置

配置swagger启动

// 配置是否启动，默认是true启动，false不启用
.enable(false)

配置了这个就会出现下面的情况：

应用：将swagger配置成在生产环境中使用，但是上线环境不启动。

使用多环境配置，配置dev(开发)、test(测试)、pro(线上)三种环境。
获取项目环境，根据环境判断是否开启swagger。

// 配置Docket的相关信息
    @Bean
    public Docket getDocket(Environment environment){
        // 环境
        Profiles profiles = Profiles.of("dev","test");
        // acceptsProfiles() 监听项目的环境，参数是Profiles对象，如果存在上面指定的环境名称，就返回true，反之false
        boolean flag = environment.acceptsProfiles(profiles);

        // 文档类型设置为DocumentationType.SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                // 设置对应的swagger的api信息，参数是一个Contact对象
                // 默认是ApiInfo实体类
                .apiInfo(this.getApiInfo())
                // 配置是否启动，默认是true启动，false不启用
                // 将flag的值作为参数传入，如果是dev或test环境就开启swagger
                .enable(flag)
                // 自定义扫描接口，select()和build()是联合使用的，只能在之间配置
                // 两种方式，选择一种
                .select()
                // apis配置扫描接口范围
                /*
                    basePackage(): 扫描指定包下的接口
                    any(): 全部扫描，默认全部扫描
                    none(): 全都不扫描
                    withMethodAnnotation(): 扫描方法上有指定注解的接口，参数是指定注解的class对象
                    RequestHandlerSelectors(): 扫描类上有指定注解的接口，参数是指定注解的class对象
                 */
//                .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
                .apis(RequestHandlerSelectors.any())
//                .apis(RequestHandlerSelectors.none())
//                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
//                .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                // 扫描过滤请求下的接口
                /*
                    ant(): 添加一个过滤请求，扫描这下面的接口
                    any(): 全部扫描
                    none(): 全都不扫描
                    regex(): 扫描满足指定正则的接口
                 */
//                .paths(PathSelectors.ant("/admin/**"))
//                .paths(PathSelectors.any())
//                .paths(PathSelectors.none())
//                .paths(PathSelectors.regex("正则字符串"))
                .build();
    }

6、Swagger分组配置

根据API文档生成多个分组，每个组对应自己的文档。多个组实际就是多个Docket对象，每一个Docket对象就是一个组。

// 组名为B
@Bean
public Docket getBDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            // 组名
            .groupName("B");
}
// 组名为C
@Bean
public Docket getCDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("C");
}
// 组名为D
@Bean
public Docket getDDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("D");
}

7、Swagger注解配置

实体类注解

当扫描的接口其中一个返回了一个实体对象，那么在swagger的model中就会有对应实体的内容。

// lombok注解
@Data
@AllArgsConstructor
@NoArgsConstructor
// swagger实体的注释，会在swagger中显示
@ApiModel("用户实体类")
public class User {
    // 实体类的字段注释
    @ApiModelProperty("自然主键")
    private Integer id;
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("用户密码")
    private String password;
}

接口注释

@Controller
public class LoginController {


    // @ApiOperation 作用于方法上，注释某一个接口
    // @ApiParam 作用于参数，用作参数的注释
    @ApiOperation("测试接口")
    @GetMapping("/test1")
    public String test1(@ApiParam("用户名参数") String username){
        return username;
    }
}

接口测试

注释注解在作用上就是一个文档的说明，没有实际上的作用。增强文档的可读性，也便于测试接口。

sun-flower__

关注

2
点赞
踩
5

收藏

觉得还不错? 一键收藏
2
评论
Swagger笔记

Swagger笔记1、Swagger简介 Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。支持在线同步API文
复制链接

扫一扫