分布式医疗挂号系统(三) | 整合Swagger2到通用模块

秒速五厘米 2022-10-22 07:41 4阅读 0赞

> 本系列文章介绍从0开始搭建一个基于分布式的医疗挂号系统。本次四篇文章完成了`医院设置微服务模块`的后端接口，为了方便开发，对`接口的返回结果`、`全局异常`、`全局日志`进行了统一处理。 同时，为了方便进行访问测试，还`整合了Swagger2工具`，这些通用的模块中，除了`全局日志`被放在医院设置微服务模块的配置资源中，其余都统一被抽取在common模块中。具体实现可参考下面文章：
> 
>  *  [医院设置微服务 | 模块搭建][Link 1]
>  *  [医院设置微服务 | 接口开发][Link 2]
>  *  [通用模块 | 整合Swagger2][_ _Swagger2]
>  *  [通用模块 | 统一返回结果、统一异常处理、统一日志处理][Link 3]
> 
> --------------------
> 
> 作者：Hudie  
> 微信公众号/CSDN博客：编程一只蝶  
> 公众号文章会比博客早1到2天，欢迎关注，每天开心~  
> 项目已开源至gitee：[https://gitee.com/guo-qianliang/yygh\_parent][https_gitee.com_guo-qianliang_yygh_parent]  
> 项目已开源至github：[https://github.com/Guoqianliang/yygh\_parent][https_github.com_Guoqianliang_yygh_parent]

### 通用模块 | 整合Swagger2 ###

*  通用模块整合swagger2步骤
 *   *  1.引入swagger依赖
     *  2.配置Swagger2
     *  3.启动类添加包扫描
     *  测试
 *  swagger常用注解

--------------------

在使用REST风格进行接口的开发测试时，post请求无法使用浏览器直接进行访问测试，目前流行的解决方案是使用Swagger2。`Swagger2是一个API接口文档，通过Swagger2可以方便各种提交方式的接口测试。`

*  通过Swagger2，我们可以看到接口名称、请求方法、传递参数、返回信息等。

# 通用模块整合swagger2步骤 #

本项目中，众多的微服务都需要整合Swagger2，所以我将其依赖引入在了通用的`common父模块`中，配置在`common_util`模块中。

## 1.引入swagger依赖 ##

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

## 2.配置Swagger2 ##

> 如下的Swagger2配置信息中分别创建了webApi分组和adminApi分组的Bean。

/** * Swagger2配置信息 */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
    
        @Bean
        public Docket webApiConfig() { 
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    //只显示api路径下的页面
                    .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                    .build();
    
        }
    
        @Bean
        public Docket adminApiConfig() { 
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("adminApi")
                    .apiInfo(adminApiInfo())
                    .select()
                    //只显示admin路径下的页面
                    .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                    .build();
    
        }
    
        private ApiInfo webApiInfo() { 
    
            return new ApiInfoBuilder()
                    .title("网站-API文档")
                    .description("本文档描述了网站微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("gql", "http://gql.com", "guoqianliang@foxmail.com"))
                    .build();
        }
    
        private ApiInfo adminApiInfo() { 
    
            return new ApiInfoBuilder()
                    .title("后台管理系统-API文档")
                    .description("本文档描述了后台管理系统微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("gql", "http://gql.com", "guoqianliang@foxmail.com"))
                    .build();
        }
    }

## 3.启动类添加包扫描 ##

Swagger2的配置类写好了，现在需要在`service_host模块`使用配置类。由于二者不在同一个项目中，所以需要在`service_host模块`的父模块的pom中引入`service_util`。而两者包名不同，还需要额外在启动类上添加包扫描。  
![引入swagger配置类][swagger]

## 测试 ##

项目启动后访问：[http://localhost:8201/swagger-ui.html][http_localhost_8201_swagger-ui.html] ，可以看到项目中接口的信息：  
![通过swagger查看后台API文档][swagger_API]  
在Controller中添加下面几个简单的Api注解，可以将swagger中的一些信息定义为中文：

![通过swagger添加注解][swagger 1]

如果需要测试接口，我们只需要点击接口下方的`Try it out` 按钮：  
![通过swagger测试方法][swagger 2]  
点击按钮后即可，看到接口的一系列返回信息：  
![通过swagger查看方法返回结果][swagger 3]

# swagger常用注解 #

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>修饰整个类，描述Controller的作用</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>描述一个类的一个方法，或者说一个接口</td> 
  </tr> 
  <tr> 
   <td>@ApiParam</td> 
   <td>单个参数描述</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>用对象来接收参数</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>用对象接收参数时，描述对象的一个字段</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>一个请求参数</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>多个请求参数</td> 
  </tr> 
 </tbody> 
</table>

[Link 1]: https://blog.csdn.net/weixin_43691058/article/details/115419552?spm=1001.2014.3001.5502
[Link 2]: https://blog.csdn.net/weixin_43691058/article/details/115437742?spm=1001.2014.3001.5502
[_ _Swagger2]: https://blog.csdn.net/weixin_43691058/article/details/115439245?spm=1001.2014.3001.5502
[Link 3]: https://blog.csdn.net/weixin_43691058/article/details/115447130?spm=1001.2014.3001.5502
[https_gitee.com_guo-qianliang_yygh_parent]: https://gitee.com/guo-qianliang/yygh_parent
[https_github.com_Guoqianliang_yygh_parent]: https://github.com/Guoqianliang/yygh_parent
[swagger]: /images/20221022/0a8250583c8541438569cbbb285bb0af.png
[http_localhost_8201_swagger-ui.html]: http://localhost:8201/swagger-ui.html
[swagger_API]: /images/20221022/0aa3d49103de41468dea5e3e0f3b0402.png
[swagger 1]: /images/20221022/07bd6c69f52a4181a27e9d740c01a248.png
[swagger 2]: /images/20221022/99d3f48210994792bbdf8c96bed0e521.png
[swagger 3]: /images/20221022/fc097cfb76834559b272778bf147449b.png