Spring boot学习之集成 swagger2 (3)

一时失言乱红尘 2022-04-18 03:17 118阅读 0赞

为什么要集成 swagger2 ?

1.  通常测试一个接口不知道该传哪些参数
2.  不知道该接口的类型，get/post全靠猜！
3.  无法很好的形成接口文档
4.  不方便调试！你是不是一边开着postman，一边不停的复制着接口和组装着参数

等等，或许… 你可以尝试下Swagger2 ！

1、在pom.xml中添加依赖

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

2、配置 swagger2 configuration，新建一个Swagger2Config配置文件

package cn.xt.app.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.context.annotation.Profile;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /* @Configuration：指定当前类是一个配置文件
     * @EnableSwagger2：开启 swagger2 功能
     * @Profile({"local"})：指定特定环境才加载，可以写多个;
     * 接口测试一般只对local/dev/sit/uat 这些环境开放，生产(prod)一般是禁用的
     * 多个参考：@Profile({"local", "dev"})
     */
    @Configuration
    @EnableSwagger2
    @Profile("local")
    public class Swagger2Config {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    // 选择哪些路径和api会生成document
                    .select()
                    // 可以指定扫描全部包
                    // .apis(RequestHandlerSelectors.any())
                    // 指定api需要扫描的包
                    .apis(RequestHandlerSelectors.basePackage("cn.xt.app.controller"))
                    // 对所有路径进行监控
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            // 标题、版本号、描述信息等信息
            return new ApiInfoBuilder()
                    .title("Spring Boot 学习")
                    .description("学习到的知识若不能很好的形成文档，久而久之就忘了曾经是否有那么回事")
                    .termsOfServiceUrl("https://blog.csdn.net/qq_20698983/article/details/83830284")
                    .version("1.0")
                    .build();
        }
    }

3、配置完成后，在 MyController 中加入几个注解，就可使用了

package cn.xt.app.controller;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    // @RestController 以JSON格式返回数据
    @RestController
    @Api(tags = "我的Controller层")
    public class MyController {
    
        // 请求名为：sayHello
        // 请求方式为：get
        @RequestMapping(value = "sayHello", method = RequestMethod.GET)
        @ApiOperation(value = "接口说明", notes = "接口发布说明")
        public String sayHello() {
            return "hello world";
        }
    
    }

4、可以看到我只是在 MyController 上面加了 @Api 注解和方法上加了 @ApiOperation注解，接下来启动项目，打开：[http://localhost:7001/swagger-ui.html][http_localhost_7001_swagger-ui.html]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70]  
5、展开后我们再看一下，图中我圈出来的就是我们配在类或者方法上的文字  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 1]  
6、点击 Try it out! 你就可以达到像在 postman 请求一样的效果，当然，功能不止这些，接下来我写几个类来验证一下。  
7、建立两个类，代码分别如下

UserLoginRequest.java
    
    private String userId;
    private String password;
    private String validateCode;
    // get/set 方法省略
    
    UserLoginResponse.java
    
    private String code;
    private String message;
    // get/set 方法省略

8、在MyController中加入如下代码，并重新启动项目

@RequestMapping(value = "login", method = RequestMethod.POST)
    @ApiOperation(value = "登录接口说明", notes = "登录接口发布说明")
    public UserLoginResponse login(@RequestBody UserLoginRequest request) {
        UserLoginResponse response = new UserLoginResponse();
        response.setCode("200");
        response.setMessage("登录成功 --> userId: " + request.getUserId()
                + " pwd: " + request.getPassword()
                + " validateCode: " + request.getValidateCode());
        return response;
    }

9、重新刷新swagger-ui页面，可以看到该方法直接将请求类(UserLoginRequest.java)和返回类(UserLoginResponse.java)全都自动解析了，以key-value的形式展示，并在后面的参数中说明了类型。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 2]  
10、输入参数，可以直接点击下图右边的模版，然后就会把模版内容自动加载到左边红色方框中，然后填入要测试的参数.  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 3]  
11、点击 Try it out! 就可以看到请求的结果。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 4]

12、更多新功能正在努力挖掘…

关于Swagger2的一些Api的使用可以参考：[Swagger2 Api 使用说明][Swagger2 Api]

工程可以直接在GitHub下载，地址为：[https://github.com/xiaotian180/spring-boot-parent.git][https_github.com_xiaotian180_spring-boot-parent.git]  
学习qq群：622038189

[http_localhost_7001_swagger-ui.html]: http://localhost:7001/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70]: /images/20220418/f3d83c3510cb4b609f218080125c0052.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 1]: /images/20220418/bdb1be97dcd84959ad2c840af761aebe.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 2]: /images/20220418/9041e67555be460f8132652a5dd24769.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 3]: /images/20220418/d1d596f9c7b042bdb3abbb87c2642d03.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIwNjk4OTgz_size_16_color_FFFFFF_t_70 4]: /images/20220418/10802de72fd54001a09c3d0dcac1403c.png
[Swagger2 Api]: https://blog.csdn.net/xupeng874395012/article/details/68946676/
[https_github.com_xiaotian180_spring-boot-parent.git]: https://github.com/xiaotian180/spring-boot-parent.git