Swagger简单应用

曾经终败给现在 2023-09-30 08:08 9阅读 0赞

**目录**

1、前后端分离

1.2、为什么要进行前后端分离

1.3、前后端分离存在的问题

2、Swagger

2.1、在项目中使用Swagger

3、SpringBoot集成Swagger

4、配置Swagger信息

5、Swagger配置扫描接口

5.1、apis

5.2、paths

6、配置是否启动Swagger

6.1、enable应用

7、配置Api文档的分组

7.1、配置多个分组

7.2、实体类配置(Model)

7.3、总结

# 1、前后端分离 #

前后端分，分离是目前一种非常流行的开发模式，它使项目的分工更加明确：

*  后端：后端控制层，服务层，数据访问层；负责处理、存储工程
 *  前端：前端控制层，视图层；负责显示数据

前端和后端是通过**接口**进行数据交换

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16][]

## 1.2、为什么要进行前后端分离 ##

*  前后端可以专注于各自擅长的领域
 *  避免后端写前端代码
 *  前端配置后端代码运行环境
 *  避免前后端发生矛盾
 *  前后端相对独立，松耦合
 *  前后端甚至可以部署在不同的服务器上

## 1.3、前后端分离存在的问题 ##

*  前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发
 *  当接口改变时，非常麻烦

解决方案：

*  首先制定schema【计划的提纲】，实时更新最新API，降低集成的风险
 *  前后端分离：
    
     *  前端测试后端接口：postman
     *  后端提供接口，需要实时更新最新的消息及改动

# 2、Swagger #

*  最流行的Api框架
 *  RestFul Api文档在线自动生成工具=>
 *  直接运行，可以直接在线测试Api接口
 *  支持多种语言：java、php...

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

总项目结构：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_11_color_FFFFFF_t_70_g_se_x_16][]

## 2.1、在项目中使用Swagger ##

在项目中使用Swagger需要springbox

*  swagger2
 *  ui

# 3、SpringBoot集成Swagger #

1.  新建SpringBoot Web项目
2.  导入相关依赖
    
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
3.  配置Swagger==>Config
    
        @Configuration
        @EnableSwagger2     //开启swagger2
        public class SwaggerConfig {
            
        }
4.  编写hello工程
    
    
    
    ![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_18_color_FFFFFF_t_70_g_se_x_16][]
5.  测试运行：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 1][]

# 4、配置Swagger信息 #

@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("天赐", "abcd...", "2312103658@qq.com");
            return new ApiInfo(
                "Swagger-Demo",
                "Swagger-test",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        }
    }

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 2][]

# 5、Swagger配置扫描接口 #

Docket.select()方法

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors，配置扫描接口方式
            //basePackage:指定要扫描的包 一般是这个
            //any:扫描全部
            //none:不扫描
            //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
            //RequestHandlerSelectors.withClassAnnotation(controller.class)
            //withMethodAnnotation：扫描方法上的注解
            //RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)
            .apis(RequestHandlerSelectors.basePackage("com.wen.swaggerdemo.controller"))
            //path():过滤xx路径
            //ant:过滤该路径下的
            //any:过滤所有
            //none:不过滤
            //regex:正则
            //.paths(PathSelectors.ant("/wen/**"))
            .build();//build前面select的方法：apis(扫描接口)、paths(过滤接口)
    }

## 5.1、apis ##

**apis中有RequestHandlerSelectors，点击进入看源码：**

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 3][]

*  RequestHandlerSelectors，配置扫描接口方式
 *  basePackage:指定要扫描的包 一般是这个
 *  any:扫描全部
 *  none:不扫描
 *  withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象 RequestHandlerSelectors.withClassAnnotation(controller.class)
 *  withMethodAnnotation：扫描方法上的注解 RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 4][]

## 5.2、paths ##

**paths中有PathSelectors，点击进入查看源码：**

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 5][]

*  path():过滤xx路径
 *  ant:过滤该路径下的
 *  any:过滤所有
 *  none:不过滤
 *  regex:正则
 *  例：.paths(PathSelectors.ant("/wen/\*\*"))

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 6][]

# 6、配置是否启动Swagger #

**Docket.enable()方法**

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //enable:是否启用Swagger，如果为False，则Swagger不能再浏览器中访问
            .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wen.swaggerdemo.controller"))
            //.paths(PathSelectors.ant("/wen/**"))
            .build();//build前面的方法：apis、paths、build
    }

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_13_color_FFFFFF_t_70_g_se_x_16][]

点击查看源码可知：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 7][]

传入布尔值：如果为False，则Swagger不能再浏览器中访问

## 6.1、enable应用 ##

**只想Swagger在生产环境中使用，但在发布时不使用**

*  判断是不是生产环境 flag=false
 *  注入enable(flag)

1.  添加两个环境application-dev.properties(项目环境)、application-pro.properties(发布环境)

![ccf71d2b719e42cda91c694841e209d0.png][]

2.在两个环境中设置各自的端口号，然后在application.properties中激活dev环境

application.properties：
    spring.profiles.active=dev
    
    application-dev.properties：
    server.port=8081
    
    application-pro.properties：
    server.port=8082：

3.因为是在enable中通过布尔值来判断是否是当前环境，所以在Docket中添加Environment，通过Environment的acceptsProfiles方法来实现。

//配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
    
        //获取项目的环境：dev
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev");
        //通过environment.acceptsProfiles(profiles)判断是否处在设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
    
        ...

点击acceptsProfiles可以看到有两个方法，但第一个方法已过期了，所以用第二个方法，第二个方法内有一个Profiles参数，所以得创建一个Profiles，Profiles便是设置要显示的环境。

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 8][]

4.启动项目可以看到，当端口号为dev：8081时，可以进入Swagger界面，但是为pro：8082时却进不了。

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_17_color_FFFFFF_t_70_g_se_x_16][]

# 7、配置Api文档的分组 #

通过Docket内的.groupName()方法来设置文档的名字

.groupName("小天")

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 9][]

## 7.1、配置多个分组 ##

可以通过创建多个Docket实例来创建多个分组，这样就可以实现每个人负责各自的组

有助于协同开发。

@Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("小小");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("小三");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("老四");
    }

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_18_color_FFFFFF_t_70_g_se_x_16 1][]

## 7.2、实体类配置(Model) ##

*  @ApiModel("")：实体类注释
 *  @ApiModelProperty("")：字段注释

@NoArgsConstructor
    @AllArgsConstructor
    @Data
    @ApiModel("用户实体类")	//实体类注释
    public class User {
        @ApiModelProperty("用户名")	//字段注释
        private String username;
        @ApiModelProperty("密码")
        private String password;
    }

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 10][]

*  @ApiOperation("")：controller方法注释
 *  @ApiParam("")：方法参数注释

//只要接口中，返回值中存在实体类，就会被扫描到swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }
    
    @ApiOperation("hello2控制类")
    @PostMapping("/hello2")
    public String user2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 11][]

## 7.3、总结 ##

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

注意：在项目发行时要关闭swagger避免出现问题以及省内存。

[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/b5910ce2acb44f668f6dd18c9b120016.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[API Documentation _ Design Tools for Teams _ Swagger]: https://swagger.io/
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_11_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/37ea223e0b0f42f9a77189f889958ef4.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_11,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_18_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/db18e01a548d4a37b79b4b77feb6314f.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_18,color_FFFFFF,t_70,g_se,x_16
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/18229266cd724f8ab802bd3ea7aab6a9.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 2]: https://img-blog.csdnimg.cn/b172a63af2de41799449c38d6e7d351a.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 3]: https://img-blog.csdnimg.cn/76dc9a45bf4b44748b43d3c2398ced33.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 4]: https://img-blog.csdnimg.cn/bb19c5fd6a6645fd8f62214544b704b0.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 5]: https://img-blog.csdnimg.cn/1683033a892d45679ed98ae0fdfce798.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 6]: https://img-blog.csdnimg.cn/5c2de653e9a843d187cda8556550c5fa.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_13_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/1cabafdb0c524352b98c5c07d695abaf.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_13,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 7]: https://img-blog.csdnimg.cn/5300702742334db6ac3a69aa5abf620b.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[ccf71d2b719e42cda91c694841e209d0.png]: https://img-blog.csdnimg.cn/ccf71d2b719e42cda91c694841e209d0.png
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 8]: https://img-blog.csdnimg.cn/cc1c226d5f494bc9b2bcdff967c17aeb.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_17_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/4a1a68c60ed544a8b62ba14a2975249e.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_17,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 9]: https://img-blog.csdnimg.cn/e03b361c57f24bfb94facc8bede01ef9.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_18_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/ce5d537f0019424b8a3a01afc8e2cd7b.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_18,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 10]: https://img-blog.csdnimg.cn/580dcf2664fd4ae2931ea8fd0ad2d54e.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA56eD5aS055qE5omT5bel5LuU_size_20_color_FFFFFF_t_70_g_se_x_16 11]: https://img-blog.csdnimg.cn/a3d3087f847740a884ddcecb4e0aa744.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA56eD5aS055qE5omT5bel5LuU,size_20,color_FFFFFF,t_70,g_se,x_16