Swagger的搭建配置

一、swagger是什么

首先来看一张图：

根据上图可知，在我们使用Restful API时，可能会出现多个终端来调用，这样就能实现一套代码，处处适用原则。但是问题就来了，Restful API我么们需要详细的文档来对应，对于维护文档可不是一件轻松的事，打个比方，在修改restful API过后，是不是也需要同步的修改文档，但此时代码还是未确认状态，所以还不能去修改文档，所以会导致restful API和文档不一致的问题。所以整合Swagger就是为了解决这类问题，并且能够减少维护文档的成本。使用Swagger能达到代码修改Api文档也同步更新的效果。

二、如何配置

2.1 导入Maven包

 		<!-- swagger2-->
     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
      </dependency>
        <!--  swagger2的web界面,导入这个依赖我们就可以通过界面查看文档了-->
     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
      </dependency>

2.2 配置Swagger

@Configuration
@EnableSwagger2  //用于开启Swagger
@EnableConfigurationProperties(SwaggerProperties.class)  
public class SwaggerAutoConfig {

    private SwaggerProperties swaggerProperties;

    public SwaggerAutoConfig(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }

    @Bean
    public Docket docket(){

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                                    .apiInfo(apiInfo())  //信息简介
                                    .select()
                                    .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())) //包扫描路径
                                    .paths(PathSelectors.any())
                                    .build();
        //安全配置
                                    docket.securitySchemes(securitySchemes()) //安全规则，securitySchemes这种方式需要使用token来验证
                                            .securityContexts(securityContexts());  //安全上下文
        return docket;

    }

    /***********
     * 安全上下文配置
     * @return
     */
    private List<SecurityContext> securityContexts() {
        return Arrays.asList(new SecurityContext(
                Arrays.asList(new SecurityReference("Authorization", new AuthorizationScope[]{new AuthorizationScope("global", "accessResource")})),
                PathSelectors.any()
        ));
    }

    /********
     * 安全规则配置
     * @return
     */
    private List<SecurityScheme> securitySchemes() {
        return Arrays.asList(new ApiKey("Authorization","Authorization","Authorization"));
    }

    /***********
     * 信息简介
     * @return
     */
    private ApiInfo apiInfo() {
       return new ApiInfoBuilder().contact(
                                   new Contact(swaggerProperties.getName(),swaggerProperties.getUrl(),swaggerProperties.getEmail())
                                )
                            .title(swaggerProperties.getTitle())   //标题名
                            .description(swaggerProperties.getDescription()) //描述信息
                            .version(swaggerProperties.getVersion())     //版本号
                            .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())     //团队地址
                .build();

    }
}

注：这里我使用了注入类swaggerProperties(@ConfigurationProperties、@EnableConfigurationProperties注解参考@ConfigurationProperties注解的理解和使用_Mr_YanMingXin的博客-优快云博客）

@Data
@ConfigurationProperties(prefix = "swagger2")
public class SwaggerProperties {

    /********
     * 包扫描路径
     */
    private String basePackage;

    /*********
     * 联系姓名
     */
    private String name;

    /*********
     * 联系人主页
     */
    private String url;

    /**********
     * 联系人邮箱
     */
    private String email;

    /************
     * 标题
     */
    private String title;

    /*********
     * 文档描述
     */
    private String description;

    /**********
     * 版本号
     */
    private String version;

    /*********
     * 团队地址
     */
    private String termsOfServiceUrl;

}

在此已经算配置好了，接下来就是配置API接口了。

2.3 API接口的配置

1）@ApiOperation注解

用于描述针对特定路径的操作或HTTP方法。 具有等效路径的操作分组在单个操作对象中。HTTP方法和路径的组合将创建唯一的操作,与下面的这个配置相关

/***********
     * 安全上下文配置
     * @return
     */
    private List<SecurityContext> securityContexts() {
        return Arrays.asList(new SecurityContext(
                Arrays.asList(new SecurityReference("Authorization", new AuthorizationScope[]{new AuthorizationScope("global", "accessResource")})),
                PathSelectors.any()
        ));
    }

2）@ApiImplicitParams注解

对请求参数的描述

3）示例

@GetMapping("swagger/test")
    @ApiOperation(value = "swagger测试方法",authorizations ={@Authorization("Authorization")} )
    @ApiImplicitParams({
            @ApiImplicitParam(name="param1",value = "参数1",dataType = "String" ,paramType = "query",example = "paramValue1"),//example表示默认值
            @ApiImplicitParam(name="param2",value = "参数2",dataType = "String" ,paramType = "query",example = "paramValue2")
    })
    public R swaggerTest(String param1,String param2){

        return R.ok("ok");
    }

4）Swagger界面

输入server/swagger-ui.html,(server为自己的服务地址，比如本地的：local host：8080）

输入token，记得带 bearer空格