swagger-ui 使用

• pom引入
  需要注意版本文体，版本不一致，具体使用的坑也不一致…

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

整合swagger-ui

# 在application.yml 中加入swagger-ui 的开启或关闭配置
# swagger 文档配置 false关闭 true 开启
swagger:
  enable: true

配置

/**
 * SwaggerConfig 配置
 * @author zy
 */
@Configuration
// 此处增加了该注解以后，不需要再启动类上增加额外注解，会二次创建bean 导致异常
@EnableSwagger2
// 此处与application中swagger-ui配置的名称一致即可完成开启与关闭
@ConditionalOnProperty(name = "enable",prefix = "swagger", havingValue = "true")
public class SwaggerConfig {

    /**
     * 构建配置
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("修改为controller的包路径即可"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .securitySchemes(Collections.singletonList(securityScheme()))
                .securityContexts(Collections.singletonList(securityContext()));
    }

    /**
     * 文档描述
     */
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "xxx api文档",
                "",
                "1.0",
                "",
                new Contact("", "", ""),
                "", "", Collections.emptyList());
    }

    /**
     * 整合Oauth 使用的对应的方式进行授权
     */
    private SecurityScheme securityScheme() {
        GrantType grantType = new ResourceOwnerPasswordCredentialsGrant(  "/oauth/token");

        return new OAuthBuilder()
                .name("spring_oauth")
                .grantTypes(Collections.singletonList(grantType))
                .scopes(Arrays.asList(scopes()))
                .build();
    }

    /**
     *安全上下文
     */
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                              .securityReferences(Collections.singletonList(new SecurityReference("spring_oauth", scopes())))
                              .forPaths(PathSelectors.any())
                              .build();
    }

    /**
     * 这里是写允许认证的scope
     */
    private AuthorizationScope[] scopes() {
        return new AuthorizationScope[]{
                new AuthorizationScope("select", "select scope is trusted!")
        };
    }

}

具体使用，个人有个人的使用方法。在开发中接口参数通常使用的实体类接收参数，而简单实用swagger-ui 会导致出现很多不需要的参数，以下是针对此问题的部分调整，会导致post测试提交失败，但是好看。

// 在swagger-ui的配置项中，另一种配置不是进行包扫描，而是扫描所有的带@Api注解的接口，具体根据实际使用
@Api(tags = "TestController", description = "测试")
@RestController
@RequestMapping("/api/test")
public class TestController extends ApiController {


    @ApiOperation("测试get方法参数")
    @ApiResponses({
            @ApiResponse(code = 1000, message = "操作成功", response = AjaxResult.class),
            @ApiResponse(code = 1001, message = "操作失败，以及操作失败原因")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "chatId", value = "群组id", required = true, paramType = "query", dataType = "String"),
    })
    @GetMapping("/getAll")
    public AjaxResult getAll(String chatId) {
        return AjaxResult.success();
    }

    @ApiOperation("测试Post方法参数")
    @ApiResponses({
            @ApiResponse(code = 1000, message = "操作成功"),
            @ApiResponse(code = 1001, message = "操作失败，以及操作失败原因")
    })
    // 页面上仅会展示以下两个参数，试过paramType换成body 也会产生部分问题，暂未解决
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "群组名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "remarks", value = "群组描述", required = false, paramType = "query", dataType = "String"),
    })
    @PostMapping("/add")
    // @ApiIgnore该注解可以忽略 ChatGroup 中的参数，仅使用ApiImplicitParams上定义的参数
    public AjaxResult add(@ApiIgnore @RequestBody TestEntity testEntity ) {
       return AjaxResult.success();
    }
}

@Data
@EqualsAndHashCode(callSuper = false)
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "测试")
public class TestEntity extends Entity {
    @ApiModelProperty("主键")
    private String id;
    @ApiModelProperty("更新时间")
    private String updateTime;
    // hidden 为true的时候，页面上不会显示该参数，一般用于不需要传参的字段
    @ApiModelProperty(value = "更新人",hidden = true)
    private String updateBy;
}

访问页面

localhost:8080/{项目路径}/swagger-ui.html
# aouth 认证 密码方式

![认证](https://img-blog.csdnimg.cn/35e6a20506ed4923aba3f809a9c779e9.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBAenlwYXNzZW5nZXI=,size_20,color_FFFFFF,t_70,g_se,x_16)