Swagger 学习笔记

最新推荐文章于 2024-11-16 09:00:00 发布

稻草人0.0

最新推荐文章于 2024-11-16 09:00:00 发布

阅读量115

点赞数

分类专栏： SpringBoot 文章标签： restful spring boot java

本文链接：https://blog.csdn.net/weixin_43989102/article/details/120539792

版权

SpringBoot 专栏收录该内容

8 篇文章 0 订阅

订阅专栏

Swagger

前后端分离后，前后端集成联调会造成无法及时协商，及时解决接口交互等问题。

前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

随着时间推移，版本迭代，接口文档往往很容易就跟不上代码。

作为一个程序员，最讨厌两件事：1、别人不写注释。2、自己写注释。

1、什么是Swagger?

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

Swagger 目标是对 RESTful API 定义一个标准且和语言无关的接口，可以让人和计算机在不访问源码、文档或通过网络流量监测的情况下发现和理解服务的功能。

Swagger 进行正确定义后，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。

Swagger 支持 API 自动生成同步的在线文档还支持在线测试。

Swagger 官网

类似的还有: Lkadoc 接口文档工具

2、SpringBoot 集成 Swagger

新建一个 SpringBootWeb项目。

导入相关依赖

3.0 之前的版本导入的依赖

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

3.0 版本之后的 Swagger 使用启动器

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

编写Helloworld

配置 Swagger （Config）

@Configuration
// @EnableSwagger2     // 开启 Swagger2  3.0之前的版本
@EnableOpenApi         // 3.0 版本
public class SwaggerConfig {
}

测试运行

访问地址：http://localhost:8080/swagger-ui/index.html 即可看见 swagger 后台界面。

3、配置 Swagger 信息

4、配置扫描接口及文档

@Configuration
// @EnableSwagger2     // 开启 Swagger2  3.0之前的版本
@EnableOpenApi      // 3.0 版本
public class SwaggerConfig {

    // 配置了 swagger 的 Docket 的 bean 实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	// 配置是否启用 swagger
            	.enable(true)
                .select()
                // RequestHandlerSelectors：配置要扫描的接口方式
                // basePackage() 指定要扫描的包
                // any() 扫描全部
                // none() 都不扫描
                // withClassAnnotation()  扫描类上的注解，参数是一个注解的返回对象
                // withMethodAnnotation()  扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                // paths(): 过滤路径
                .paths(PathSelectors.ant("/example/**"))
                .build();
    }

    // 配置 Swagger 信息 apiInfo
    private ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact("面包", "http://localhost", "843818747@qq.com");
        return new ApiInfo(
                "面包 API 文档",
                "这个是描述",
                "1.0",
                "http://localhost",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

Swagger在特定环境中使用：

判断所使用的环境（application-dev.properties、application-pro.properties、application-test.properties）

注入 enable( false )

# application.properties
spring.profiles.active=dev

// 可以使注解获取环境
@Value("${spring.profiles.active}")
private String env;
-----------------------------------------------------------------
    
// 设置要显示的 Swagger 环境
Profiles profiles = Profiles.of("dev", "test");
// 获取项目的环境
boolean flag = environment.acceptsProfiles(profiles);

5、配置API文档的分组

.groupName("面包")

一个 Docket 对应一个分组：

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组1");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组2");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组3");
}