SpringBoot之整合Swagger2分析和实现-基于Spring Boot2.0.2版本

男娘i 2022-05-18 23:20 101阅读 0赞

\#\#\#概念介绍

*  随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。  
    前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。  
    \#\#\#整合步骤
 *  依赖导入
    
        <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>
    
     *  添加SwaggerConfiguration

@Configuration
    @EnableSwagger2// 必须加此注解
    public class SwaggerConfiguration {
    
        @Autowired
        JWTConstant jwtConstant;
    
        @Bean
        public Docket createRestApi() {
            // jwt验证解决
            ParameterBuilder pb = new ParameterBuilder();
            List<Parameter> token = new ArrayList<>();
            pb.name(jwtConstant.JWT_HEADERS).description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
            token.add(pb.build());
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(new ApiInfoBuilder().title("FrameWork 开发平台接口文档").description("Based On Spring Boot").termsOfServiceUrl("").version("1.0").build())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.cherry"))
                    .paths(PathSelectors.any())
                    .build()
                    .globalOperationParameters(token);
        }
    }

*  在spring security的配置中对swagger的url进行放行  
    在congiure的方法中添加如下例外路径
    
        .antMatchers(serverPath + "/swagger-ui.html").permitAll()
                      .antMatchers(serverPath + "/swagger-resources/**").permitAll()
                      .antMatchers(serverPath + "/images/**").permitAll()
                      .antMatchers(serverPath + "/webjars/**").permitAll()
                      .antMatchers(serverPath + "/v2/api-docs").permitAll()
                      .antMatchers(serverPath + "/configuration/ui").permitAll()
                      .antMatchers(serverPath + "/configuration/security").permitAll()
 *  添加注解（非必须）
    
     *  swagger2常用注解
    
    >  *  @Api()用于类；  
    >     表示标识这个类是swagger的资源

>  *  @ApiOperation()用于方法；  
>     表示一个http请求的操作
>  *  @ApiParam()用于方法，参数，字段说明；  
>     表示对参数的添加元数据（说明或是否必填等）
>  *  @ApiModel()用于类  
>     表示对类进行说明，用于参数用实体类接收
>  *  @ApiModelProperty()用于方法，字段  
>     表示对model属性的说明或者数据操作更改
>  *  @ApiIgnore()用于类，方法，方法参数  
>     表示这个方法或者类被忽略
>  *  @ApiImplicitParam() 用于方法  
>     表示单独的请求参数
>  *  @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明： 
    @Api() 
    用于类；表示标识这个类是swagger的资源 
    tags–表示说明 
    value–也是说明，可以使用tags替代 
    但是tags如果有多个值，会生成多个list

*  注解实例

@RestController
    @Api(value = "首页", tags = "首页")
    public class IndexController extends BaseController {
    
        /**
         *  注册
         *
         * @param userEntity
         * @throws BusinessException
         */
        @PostMapping(value = "${jwt.jwt_route_register}")
        @ApiOperation(value = "用户注册")
        public UserEntity register(UserEntity userEntity) throws BusinessException {
            userEntity.setCreateDate(new Date());
            userEntity.setStatus(1);
            userEntity.setBindType(1);
            UserEntity entity = userService.save(userEntity);
            entity.setPassword("");
            entity.setBindType(null);
            entity.setStatus(null);
            return entity;
        }
    
    
        /**
         * 登录
         *
         * @param loginName
         * @param password
         * @return
         * @throws BusinessException
         */
        @PostMapping(value = "/${jwt.jwt_route_authentication_path}")
        public String login(@ApiParam(value = "登录名", required = true) String loginName,@ApiParam(value = "密码", required = true) String password) throws BusinessException {
            String token = userService.login(loginName, password);
            return token;
        }
    
    }

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

*  userEntity中是的注解

@ApiModelProperty(value = "id")
             private Integer id;
             @ApiModelProperty(value = "登录名")
             private String loginName;

### 可能出现的问题 ###

*  访问方法，返回403；考虑jwt口令验证问题
 *  无法访问http://localhost:8080/swagger-ui.html页面，出现白页或者弹框。考虑是spring security的url路径配置问题。解决方法：需要把swagger2的相关的url添加到其中去。

### 总结 ###

*  页面效果  
    ![这里写图片描述][70]  
    ![这里写图片描述][70 1]  
    ![这里写图片描述][70 2]  
    下面可以点“try it now”可以直接进行测试啦。虽然没有postman那么强大，但是对于前后端分离的项目的来说，使用还是比较方便的，而且很快速。
 *  java中还有不少好用的脚手架，swagger就是其中一个。后面我会继续更新的。

[70]: /images/20220519/a2f5813e4ea04c44adc446168c50e83a.png
[70 1]: /images/20220519/9297f1e2d0f64588abacea4a978deaf2.png
[70 2]: /images/20220519/144b131ec49443cc983f9bb84c2f9139.png