架构师

您现在的位置是:首页 > 技术博客 > 框架整合

框架整合

如何在生产环境优雅的关闭Swagger2?

架构师小跟班 2020-05-12 框架整合
1、什么是swagger?Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。2、swagger的作用是什么?1)接口的文档在线自动生成。2)功能测试。3

1、什么是swagger?

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2、swagger的作用是什么?

1)接口的文档在线自动生成。

2)功能测试。

3、swagger如何使用?

第一步:导入swagger依赖包

<dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger2</artifactId>

      <version>2.6.1</version>

</dependency>

<dependency>

     <groupId>io.springfox</groupId>

     <artifactId>springfox-swagger-ui</artifactId>

     <version>2.6.1</version>

</dependency>

第二步:创建swagger配置文件

package com.ryi.rpcs.framework.config;

import java.util.ArrayList;
import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2的接口配置
 * 架构师小跟班
 * @author https://www.jiagou1216.com
 */
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {
    /**
     * 系统基础配置
     */
    @Autowired
    private RpcsConfig rpcsConfig;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/dev-api")
                // 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api,用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.ryi.rpcs.project.tool.swagger"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                /* 设置安全模式,swagger可以设置访问token */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     * 安全模式,这里指定token通过Authorization头请求头传递
     */
    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题:快速预安检系统_接口文档")
                // 描述
                .description("描述:用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                // 作者信息
                .contact(new Contact(rpcsConfig.getName(), null, null))
                // 版本
                .version("版本号:" + rpcsConfig.getVersion())
                .build();
    }
}

4、注解及其说明

@Api : 用在类上,描述该类的主要作用。

@ApiOperation:用在方法上,给API增加方法描述。

@ApiImplicitParams : 用在方法上,包含一组参数描述。

@ApiImplicitParam:用来注解来给方法入参增加描述。

@ApiResponses:用于表示一组响应。

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

code:数字,例如500

message:信息,例如"请求参数异常"

response:抛出异常的类

@ApiModel:用在返回对象类上,描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)。

@ApiModelProperty:描述一个model的属性。

关闭Swagger有两种方式

方式一:

在Swagger2Config上使用@Profile注解标识,@Profile({"dev","test"})表示在dev和test环境才能访问swagger-ui.html,prod环境下访问不了。

方式二:

在Swagger2Config上使用@ConditionalOnProperty注解,

@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")

表示配置文件中如果swagger.enable =true表示开启。所以只需要在开发环境的配置文件配置为true,生产环境配置为false即可。

本人比较喜欢第一种方式,因为第二种方式还要在每个环境文件中去配置,并维护;Swagger一般用于开发和测试环境,所以直接限制Swagger启用的环境为dev和test即可,这样也不需要再维护配置文件了。

文章评论