SpringBoot框架整合SwaggerUI

SpringBoot框架整合SwaggerUI

  • 整合swagger进行模块测试

    • 注意事项:为方便SpringBoot更好的整合Swagger,需要专门放置在一个模块中(maven子工程)

    • 创建公共模块,整合swagger,为了所有模块进行使用

      • common/pom.xml,导入相关的依赖
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
                <scope>provided </scope>
            </dependency>
        
            <!--mybatis-plus-->
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-boot-starter</artifactId>
                <scope>provided </scope>
            </dependency>
        
            <!--lombok用来简化实体类:需要安装lombok插件-->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <scope>provided </scope>
            </dependency>
        
            <!--swagger-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <scope>provided </scope>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <scope>provided </scope>
            </dependency>
        
            <!-- redis -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-data-redis</artifactId>
            </dependency>
        
            <!-- spring2.X集成redis所需common-pool2
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-pool2</artifactId>
                <version>2.6.0</version>
            </dependency>-->
        </dependencies>
        
    • 在公共模块下在创建一个模块,如service_base

      • 在该模块下创建配置类(需要遵循SpringBoot规范,该代码固定)
        package com.xsha.servicebase;
        
        import com.google.common.base.Predicates;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import springfox.documentation.builders.ApiInfoBuilder;
        import springfox.documentation.builders.PathSelectors;
        import springfox.documentation.service.ApiInfo;
        import springfox.documentation.service.Contact;
        import springfox.documentation.spi.DocumentationType;
        import springfox.documentation.spring.web.plugins.Docket;
        import springfox.documentation.swagger2.annotations.EnableSwagger2;
        
        @Configuration
        @EnableSwagger2
        public class SwaggerConfig {
            @Bean
            public Docket webApiConfig(){
                return new Docket(DocumentationType.SWAGGER_2)
                        .groupName("webApi")
                        .apiInfo(webApiInfo())
                        .select()
                        .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                        .paths(Predicates.not(PathSelectors.regex("/error.*")))
                        .build();
        
            }
        
            private ApiInfo webApiInfo(){
        
                return new ApiInfoBuilder()
                        .title("网站标题")
                        .description("接口文档的描述信息")
                        .version("1.0")
                        .contact(new Contact("java", "http://www.baidu.com", "1234567890@qq.com"))
                        .build();
            }
        }
        
    • 使用方式

      • 在其他模块(最好是最外层的)的pom.xml引入上面的模块即可

        <dependency>
            <groupId>com.xsha</groupId>
            <artifactId>service_base</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>
        
      • 在该模块的启动类上添加ComponentScan注解,指定需要扫描的包。例如:@ComponentScan(basePackages={“com.xsha”})

      • 然后启动,访问地址:http://127.0.0.1:8001/swagger-ui.html

    • 统一返回结果的格式(自定义结果)

      • 在公共模块下在创建一个模块,如common-utils

      • 创建一个专门管理状态码的接口

        public interface ResultCode {
        
            //定义两个状态码
            public static int SUCCESS = 20000;
            public static int ERROR = 40000;
        }
        
      • 定义返回格式(较为固定)

        package com.xsha.commonutils;
        
        import io.swagger.annotations.ApiModelProperty;
        import lombok.Data;
        
        import java.util.HashMap;
        import java.util.Map;
        
        // 统一返回结果类
        @Data
        public class R {
        
            @ApiModelProperty(value = "是否成功")
            private Boolean success;
        
            @ApiModelProperty(value = "返回码")
            private Integer code;
        
            @ApiModelProperty(value = "返回消息")
            private String message;
        
            @ApiModelProperty(value = "返回数据")
            private Map<String, Object> data = new HashMap<String, Object>();
        
            // 把构造方法定为私有
            private R() {}
        
            // 成功静态方法
            public static R ok() {
                R r = new R();
                r.setSuccess(true);
                r.setCode(ResultCode.SUCCESS);
                r.setMessage("成功");
                return r;
            }
        
            // 失败静态方法
            public static R error() {
                R r = new R();
                r.setSuccess(false);
                r.setCode(ResultCode.ERROR);
                r.setMessage("失败");
                return r;
            }
        
            public R success(Boolean success){
                this.setSuccess(success);
                return this;
            }
        
            public R message(String message){
                this.setMessage(message);
                return this;
            }
        
            public R code(Integer code){
                this.setCode(code);
                return this;
            }
        
            public R data(String key, Object value){
                this.data.put(key, value);
                return this;
            }
        
            public R data(Map<String, Object> map){
                this.setData(map);
                return this;
            }
        
        }
        
      • 使用方式

        • 在其他模块(最好是最外层的)的pom.xml引入上面的模块即可

          <dependency>
              <groupId>com.xsha</groupId>
              <artifactId>common_utils</artifactId>
              <version>0.0.1-SNAPSHOT</version>
          </dependency>
          
        • 每次返回的结果的类型必须是自定义的“返回格式”类类型

          // please use rest style
          // 1.select all teachers data
          @ApiOperation(value = "所有数据列表")
          @GetMapping("findAll")
          public R findAllTeachers() {
              List<EduTeacher> teachers = teacherService.list(null);
              return R.ok().data("results", teachers);
          }
          
          // request path mast have variable id
          // 2.logically delete teacher
          @ApiOperation(value = "逻辑删除数据")
          @DeleteMapping("{id}")
          public R logicDeleteTeacher(@ApiParam(name="id", value="讲师ID", required = true) @PathVariable String id) {
              boolean flag = teacherService.removeById(id);
              return flag? R.ok(): R.error();
          }
          
        • 最后在swagger中测试即可

hmoban主题是根据ripro二开的主题,极致后台体验,无插件,集成会员系统
自学咖网 » SpringBoot框架整合SwaggerUI