2023-2-1 前端达人
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势
通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-spring-web</artifactId> <version>2.9.2</version> </dependency> <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>
在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java
@Configuration // 配置类 @EnableSwagger2 // 开启 swagger2 的自动配置 public class SwaggerConfig { }
这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8080/swagger-ui.html# （这里我的项目端口是 8868 ，项目路径是 /mike，所以我打开的文档地址为 http://localhost:8868/mike/swagger-ui.html# ）即可查看 swagger 文档。
可以看到 Swagger 文档中大概有这四类信息
Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。
Swagger 默认的基本信息展示
ApiInfo 中默认的基本设置
SwaggerConfig.java 配置文件添加以下内容：
@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) // 配置基本信息 .apiInfo(apiInfo()) ; } // 基本信息设置 private ApiInfo apiInfo() { Contact contact = new Contact( "米大傻", // 作者姓名 "https://blog.csdn.net/xhmico?type=blog", // 作者网址 "777777777@163.com"); // 作者邮箱 return new ApiInfoBuilder() .title("多加辣-接口文档") // 标题 .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述 .termsOfServiceUrl("https://www.baidu.com") // 跳转连接 .version("1.0") // 版本 .license("Swagger-的使用(详细教程)") .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535") .contact(contact) .build(); }
重启服务，打开 Swagger 文档，基本信息改变如下所示：
默认情况下，Swagger 是会展示所有的接口信息的，包括最基础的 basic-error 相关的接口
有时候我们希望不要展示 basic-error-controller 相关的接口，或者是说这想要显示某些接口，比如说：user-controller 下的接口，由该怎么去实现呢？这个时候就需要设置 扫描接口
@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors //.any() // 扫描全部的接口，默认 //.none() // 全部不扫描 .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用 //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口 //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口 ) .paths(PathSelectors .any() // 满足条件的路径，该断言总为true //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger） //.ant("/user/**") // 满足字符串表达式路径 //.regex("") // 符合正则的路径 ) .build(); }
可根据自己的需求去设置对应的配置，这里我就不再一一赘述了，以上是我所设置的配置，重启服务，打开 Swagger 文档，接口信息改变如下所示：
可以看到之前 basic-error-controller 相关的接口已经没有了
Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
swagger 文档中组名默认是 default，可通过 .groupName(String )
@Bean public Docket docket() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改组名为 "mike" ; }
修改后：
如果需要配置多个组的话，就需要配置多个 docket() 方法，这里我就简单写两组，代码如下：
/** * 展示 controller 包下所有的接口 */ @Bean public Docket docket1() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改组名为 "mike" // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用 ) .paths(PathSelectors .any() // 满足条件的路径，该断言总为true ) .build(); } /** * 展示路径为 /error 的所有接口（基础接口） */ @Bean public Docket docket2() { // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("yank") // 修改组名为 "yank" // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors .any() // 扫描全部的接口，默认 ) .paths(PathSelectors .ant("/error") // 满足字符串表达式路径 ) .build(); }
重启服务，打开 Swagger 文档，接口信息改变如下所示：
组名为 mike 的文档中只有 user-controller 相关的接口信息
组名为 yank 的文档中只有 basic-error-controller 相关的接口信息
在开发或者测试环境下，我们开启 swagger 会方便前端和后端的交互，但是如果在生产环境下也开启 swagger 的话，是会将接口暴露出去的，有极大风险，如何让 swagger 根据不同的环境来决定是否开启？
这里我准备了四个项目的配置文件，dev、test、pro 三个环境的配置文件仅是端口上的不同
application.yml 内容如下，用于指定选择的环境：
spring: profiles: active: dev
可以通过代码判断此时是在什么环境：dev、test、pro，如果是在 pro 生产环境，则关闭 swagger。
/** * swagger 配置 * @param environment 环境 */ @Bean public Docket docket(Environment environment) { // 设置环境范围 Profiles profiles = Profiles.of("dev","test"); // 如果在该环境返回内则返回：true，反之返回 false boolean flag = environment.acceptsProfiles(profiles); // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .enable(flag) // 是否开启 swagger：true -> 开启，false -> 关闭 ; }
在 application.yml 全局配置文件中环境指向 dev 时，是可以打开 swagger 的
如果我将 application.yml 全局配置文件中环境指向 pro 时，就不能打开 swagger 了，提示 Could not render e, see the console
之前有说 Swagger 会将接口请求或者相应的实体类信息展示在 Models 下的，比如我 UserController.java 下有一个接口如下所示：
@PostMapping(value = "/query-user-info") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }
它的请求体是 IdReq，响应是 ResponseBean，Models 展示这两个实体类信息如下：
前端可通过看这个 Models 知道后端定义实体类的信息。
该注解是作用于类上面的，是用来描述类的一些基本信息的。
相关属性：
value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
譬如：这个为给 IdReq 这个类添加该注解
@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id请求体") public class IdReq { private String id; }
可以看到这里的名字从 IdReq 变成 Id请求体 了
它的作用是添加和操作属性模块的数据。
该注解的使用详情可参见博客：@ApiModelProperty注解的用法
这里我还是以 IdReq 类为例，为该类的属性添加说明
@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id请求体") public class IdReq { @ApiModelProperty("主键id") private String id; }
可以看到这里对该字段有一个备注说明。
该注解用来对某个方法/接口进行描述
该注解的使用详情可参见博客：Swagger @ApiOperation 注解详解
这里我以 UserController 下的接口为例：
@PostMapping(value = "/query-user-info") @ApiOperation(value = "根据id查询用户详情") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }
可以看见该接口就多了对其的描述信息。
该注解使用在方法上或者参数上，字段说明，表示对参数的添加元数据（说明或者是否必填等）
相关属性：
这里我以 UserController 下的接口为例：
@PostMapping(value = "/query-user-infos") @ApiOperation(value = "条件查询用户信息") public ResponseBean queryUserInfos( // name 用户名称 不必填 @ApiParam(value = "用户名称", required = false) @RequestParam(required = false) String name, // gender 用户性别 必填 @ApiParam(value = "用户性别", required = true) @RequestParam(required = true) GenderEnum gender ) { return ResponseBean.success(userService.queryUserInfos(name,gender)); }
这里会展示请求参数的备注信息，以及是否必填等。
使用 swagger 除了让前后端交互变得方便，也让接口的请求变得简单，只需要填写好请求所需要的参数信息，便可直接发起请求。
比如说接口 /user/query-user-info
点击 Try it out
设置好请求所需的参数，点击 Execute 执行
就能看到接口响应的结果了
接口 /user/query-user-infos 也差不多
有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。
@Bean public Docket docket() { // 设置请求头 List<Parameter> parameters = new ArrayList<>(); parameters.add(new ParameterBuilder() .name("token") // 字段名 .description("token") // 描述 .modelRef(new ModelRef("string")) // 数据类型 .parameterType("header") // 参数类型 .defaultValue("default value") // 默认值：可自己设置 .hidden(true) // 是否隐藏 .required(false) // 是否必须 .build()); // 创建一个 swagger 的 bean 实例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改组名为 "mike" // 配置接口信息 .select() // 设置扫描接口 // 配置如何扫描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用 ) .paths(PathSelectors .any() // 满足条件的路径，该断言总为true ) .build() // 添加请求头参数 .globalOperationParameters(parameters); }
比如接口：
@GetMapping(value = "/get-token") @ApiOperation(value = "获取请求头中的token信息") public void getToken( @RequestHeader(value = "token",required = false) String token ) { // 直接获取 token 信息 System.out.println("token = " + token); // 通过代码获取 ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); if (servletRequestAttributes != null) { HttpServletRequest request = servletRequestAttributes.getRequest(); String header = request.getHeader("token"); System.err.println("header = " + header); } }
可以看到这个接口已经可以去设置请求头了，调用接口
后端也能获取到。
分享此文一切功德，皆悉回向给文章原作者及众读者.
免责声明：蓝蓝设计尊重原作者，文章的版权归原作者。如涉及版权问题，请及时与我们取得联系，我们立即更正或删除。
蓝蓝设计( www.lanlanwork.com )是一家专注而深入的界面设计公司，为期望卓越的国内外企业提供卓越的UI界面设计、BS界面设计 、 cs界面设计 、 ipad界面设计 、 包装设计 、 图标定制 、 用户体验 、交互设计、 网站建设 、平面设计服务、UI设计公司、界面设计公司、UI设计服务公司、数据可视化设计公司、UI交互设计公司、高端网站设计公司、UI咨询、用户体验公司、软件界面设计公司
蓝蓝设计的小编 http://www.lanlanwork.com