• Spring boot整合Swagger2接口文档使用


    背景:
    最近进行项目优化,增添swagger功能方便接口测试!

    一、SWAGGER简介

    Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

    作用:

    1. 接口的文档在线自动生成。
    2. 功能测试。

    Swagger是一组开源项目,其中主要要项目如下:

    Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
    Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
    Swagger-js: 用于JavaScript的Swagger实现。
    Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
    Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
    Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

    二、SPRINGBOOT整合流程

    1.POM.XML中添加MAVEN依赖

    此处需要注意的是版本问题,高版本的swagger必须对应高版本的springboot,我们项目集成的是 springboot1.5.9 + swagger2.2.2

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

    2.增加SWAGGERCONFIG配置类

    /**
     * Swagger配置类
     * @Author: yuanj
     * @Date: 2018/9/17 13:43
     */
    @Configuration
    @EnableSwagger2
    @ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true")
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                      //这里采用包含注解的方式来确定要显示的接口
                    //.apis(RequestHandlerSelectors.basePackage("com.moerlong.service_authorize.controller"))    //这里采用包扫描的方式来确定要显示的接口
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("MoerService Gateway Doc")                       //标题
                    .description("摩尔服务授权网关 Api文档")                  //描述
                    .termsOfServiceUrl("http://www.moerlong.com")           //条款地址(不可见)
                    .contact("moerlong")                                    //作者信息
                    .version("1.0")                                         //版本号
                    .build();
        }
    
    }

    注意此处使用了@ConditionalOnProperty标签,可以配合application.yml进行swagger的开关配置:

    @ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true")

    application.yml 中添加:

    msg-config:
      swagger-open: true

    其中name用来从application.yml中读取某个属性值,如果该值为空,则返回false;如果值不为空,则将该值与havingValue指定的值进行比较,如果一样则返回true;否则返回false。如果返回值为false,则该configuration不生效;为true则生效。

    3.在CONTROLLER层添加相关注解

    Swagger使用的注解及其说明:

    @Api:用在类上,说明该类的作用。

    @ApiOperation:注解来给API增加方法说明。

    @ApiImplicitParams : 用在方法上包含一组参数说明。

    @ApiImplicitParam:用来注解来给方法入参增加说明。

    @ApiResponses:用于表示一组响应

    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

    @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

    @ApiImplicitParam的参数说明:
    在这里插入图片描述

    注:paramType 必须与方法参数获取使用的注解一致,不然无法接受到参数值

    实际案例:

    @RestController
    @RequestMapping("/teacher")
    @Api(value = "UserController", description = "老师相关接口")
    public class TeacherController {
    
        @Autowired
        private TeacherService teacherSvc;
    
        @OpenApi
        @RequestMapping(value = "findPage", method = RequestMethod.POST)
        @ApiOperation(value = "findPage", notes = "首页查询老师列表")
        public ResponseFindPage<TeacherResponse> findPage(@RequestBody TeacherSearchRequest body) {
            return teacherSvc.findPage(body);
        }
    
        @OpenApi
        @RequestMapping(value = "auth", method = RequestMethod.GET)
        @ApiOperation(value = "auth", notes = "鉴权")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType = "query", name = "code", value = "code", required = true, dataType = "String"),
                @ApiImplicitParam(paramType = "query", name = "encryptedData", value = "encryptedData", required = true, dataType = "String"),
                @ApiImplicitParam(paramType = "query", name = "iv", value = "iv", required = true, dataType = "String")
        })
        public ResponseMessage<UserResponse> auth(@RequestParam String code, @RequestParam String encryptedData, @RequestParam String iv) {
            return userService.auth(code, encryptedData, iv);
        }
    }

    4.访问SWAGGER地址

    默认地址:http://localhost:8885/swagger-ui.html
    在这里插入图片描述

    在这里插入图片描述

    在这里插入图片描述

    参考原文:https://www.freesion.com/article/9180461/

    代码改变世界!

  • 相关阅读:
    Ubuntu kylin 14.04 安装问题未解决
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
    C 语言实例
  • 原文地址:https://www.cnblogs.com/xiaobug/p/14072900.html
Copyright © 2020-2023  润新知