Swagger总结

女爷i 2022-09-08 00:12 109阅读 0赞

# Swagger #

*  了解前后端分离
 *  在SpringBoot中集成Swagger

### Swagger简介 ###

**前后端分离**

Vue + SpringBoot

后端时代：前端只用管理静态页面；html==>后端。 模块引擎 JSP=>后端主力

前后端分离时代：

*  后端： 后端控制层，服务层，数据访问层
 *  前端： 前端控制层，视图层
    
     *  伪造后端数据，json。
 *  前后端如何交互？==> API
 *  前后端相对独立，松耦合；
 *  前后端甚至可以部署在不同的服务器上；

产生问题：

*  前后端集成联调。及时协商，尽早解决。

解决方案：

*  首先指定schema，实时更新更新API，降低集成风险
 *  以前：指定word计划文档；
 *  前后端分离：
    
     *  前端测试后端接口：postman
     *  后端提供接口，需要实时更新最新消息及改动

### Swagger ###

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

官网：[API Documentation & Design Tools for Teams | Swagger][API Documentation _ Design Tools for Teams _ Swagger]

在项目中使用Swagger需要springbox；

*  swagger2
 *  ui

### SpringBoot集成Swagger ###

1.  新建一个SpringBoot Web项目
2.  导入相关依赖

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

1.  编写Hello工程
2.  配置Swagger==>Config

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

1.  测试运行: [Swagger UI][]

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

### 配置Swagger ###

Swagger的bean实例Docket

@Configuration
    @EnableSwagger2 // 开启Swagger 2
    public class SwaggerConfig { 
    
        // 配置Swagger的Docket的实例
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
    
        // 配置Swagger信息 apiInfo
        private ApiInfo apiInfo() { 
    
            // 作者信息
            Contact contact = new Contact("Dao Chang","www.unsure.com","goslinezhang@qq.com");
    
            return new ApiInfo(
                    "gosline的Swagger API文档",
                    "逆水行舟者，不进则退",
                    "version 1.0",
                    "有待创建",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList()
            );
        } 
    }

Swagger配置扫描接口

Docket.select()

// 配置了Swagger的Docket的bean实例 
    @Bean
    public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                    .select()
                    // RequestHandlerSelectors, 配置要扫描接口的方式
    // basePacket：指定要扫描的包
                    // any() 扫描全部
                    // none() 不扫描
                    // withClassAnnotation: 扫描类上的注解 参数未注解的反射对象
                    // withMethodAnnotation: 扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.gosline.swagger.controller"))
                    // paths() 过滤路径
                    .paths(PathSelectors.ant("/gosline/**"))
                    .build();
        }

配置是否启动Swagger

// 配置Swagger的Docket的实例
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2).
                    apiInfo(apiInfo())
                    // enable是否启动Swagger，如果为False，则Swagger不能在浏览器中访问
                  .enable(false)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.gosline.swagger.controller"))
    // .paths(PathSelectors.ant("/gosline/**"))
                    .build();
        }

希望Swagger在生产环境中使用，在发布的时候不使用？

*  判断是不是生产环境 flag = false
 *  注入enable（flag）

// 配置Swagger的Docket的实例
        @Bean
        public Docket docket(Environment environment) { 
    
            // 设置要现实的Swagger环境
            Profiles profiles = Profiles.of("dev", "test");
            // 获取项目的环境
            boolean flag = environment.acceptsProfiles(profiles);
            System.out.println(flag);
    
            return new Docket(DocumentationType.SWAGGER_2).
                    apiInfo(apiInfo())
                    // enable是否启动Swagger，如果为False，则Swagger不能在浏览器中访问
                .groupName("gosline") // 重要
                  .enable(flag)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.gosline.swagger.controller"))
    // .paths(PathSelectors.ant("/gosline/**"))
                    .build();
        }

总结：

1.  通过Swagger给比较难理解的属性或者接口增加注释信息
2.  接口文档实时更新
3.  在线测试

【注意点】在正式发布时，关闭Swagger

致敬狂神：欢迎收看：[狂神视频][Link 1]

[API Documentation _ Design Tools for Teams _ Swagger]: https://swagger.io/
[Swagger UI]: http://localhost:8080/swagger-ui.html
[Link 1]: https://www.bilibili.com/video/BV1Y441197Lw?p=4&spm_id_from=pageDriver