• Swagger 官方 Starter 配上这个增强方案是真的香!


    Swagger 官方 Starter 配上这个增强方案是真的香!

    这篇文章,简单给大家聊聊项目必备的 Swagger 该怎么玩。

    何为 Swagger ? 简单来说,Swagger 就是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。

    为何要用 Swagger ? 前后端分离的情况下,一份 Rest API 文档将会极大的提高我们的工作效率。前端小伙伴只需要对照着 Rest API 文档就可以搞清楚一个接口需要的参数以及返回值。通过 Swagger 我们只需要少量注解即可生成一份自带 UI 界面的 Rest API 文档,不需要我们后端手动编写。并且,通过 UI 界面,我们还可以直接对相应的 API 进行调试,省去了准备复杂的调用参数的过程。

    这篇文章的主要内容:

    1. SpringBoot 项目中如何使用?
    2. Spring Security 项目中如何使用?
    3. 使用 knife4j 增强 Swagger

    以下演示所用代码,你可以在这个仓库找到:https://github.com/Snailclimb/spring-security-jwt-guide (从零入门 !Spring Security With JWT(含权限验证)后端部分代码)

    SpringBoot 项目中如何使用?

    Swagger3.0 官方已经有了自己的 Spring Boot Starter,只需要添加一个 jar 包即可(SpringBoot 版本 2.3.6.RELEASE)。。

    <!-- swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

    什么都不用配置!直接在浏览器中访问 :http://ip:port/swagger-ui/ 即可。

    图片

    Spring Security 项目中如何使用?

    如果你的项目使用了 Spring Security 做权限认证的话,你需要为 Swagger 相关 url 添加白名单。

        String[] SWAGGER_WHITELIST = {
                "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**"
        };

        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http.cors().and()
                    // 禁用 CSRF
                    .csrf().disable()
                    .authorizeRequests()
                    // swagger
                    .antMatchers(SWAGGER_WHITELIST).permitAll()
              ......
        }

    另外,某些请求需要认证之后才可以访问,为此,我们需要对 Swagger 做一些简单的配置。

    配置的方式非常简单,我提供两种不同的方式给小伙伴们。

    1. 登录后自动为请求添加 token。
    2. 为请求的 Header 添加一个认证参数,每次请求的时候,我们需要手动输入 token。

    登录后自动为请求添加 token

    通过这种方式我们只需要授权一次即可使用所有需要授权的接口。

    图片

    /**
     * @author shuang.kou
     * @description swagger 相关配置
     */
    @Configuration
    public class SwaggerConfig {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
                    .paths(PathSelectors.any())
                    .build()
                    .securityContexts(securityContext())
                    .securitySchemes(securitySchemes());
        }

        private List<SecurityScheme> securitySchemes() {
            return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
        }

        private List<SecurityContext> securityContext() {
            SecurityContext securityContext = SecurityContext.builder()
                    .securityReferences(defaultAuth())
                    .build();
            return Collections.singletonList(securityContext);
        }

        List<SecurityReference> defaultAuth() {
            AuthorizationScope authorizationScope
                    = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
            authorizationScopes[0] = authorizationScope;
            return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Security JWT Guide")
                    .build();
        }
    }

    未登录前:

    图片

    登录后:

    图片

    为请求的 Header 添加一个认证参数

    每次请求的时候,我们需要手动输入 token 到指定位置。

    图片

    @Configuration
    public class SwaggerConfig {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
                    .paths(PathSelectors.any())
                    .build()
                    .globalRequestParameters(authorizationParameter())
                    .securitySchemes(securitySchemes());
        }

        private List<SecurityScheme> securitySchemes() {
            return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
        }

        private List<RequestParameter> authorizationParameter() {
            RequestParameterBuilder tokenBuilder = new RequestParameterBuilder();
            tokenBuilder
                    .name("Authorization")
                    .description("JWT")
                    .required(false)
                    .in("header")
                    .accepts(Collections.singleton(MediaType.APPLICATION_JSON))
                    .build();
            return Collections.singletonList(tokenBuilder.build());
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Security JWT Guide")
                    .build();
        }
    }

    使用 knife4j 增强 Swagger

    Swagger 原生提供的界面使用体验比较差。常用的增强 Swagger 的方案有下面两种:

    1. YApi :YApi 是一个可本地部署的、打通前后端及 QA 的、可视化的接口管理平台。可以帮助我们让 swagger 页面的体验更加友好,目前很多大公司都在使用这个开源工具。项目地址:https://github.com/YMFE/yapi 。使用方法:当 Swagger 遇上 YApi,瞬间高大上了!

    2. Knife4j :Swagger 生成 Api 文档的增强解决方案,前身是 swagger-bootstrap-ui 。官方文档:https://xiaoym.gitee.io/knife4j/documentation/ 。

    根据官网介绍,knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案。

    项目地址:https://gitee.com/xiaoym/knife4j 。

    使用方式非常简单,添加到相关依赖即可(SpringBoot 版本 2.3.6.RELEASE)。

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>3.0.2</version>
    </dependency>

    完成之后,访问:http://ip:port/doc.html 即可。

    效果如下。可以看出,相比于 swagger 原生 ui 确实好看实用了很多。

    图片

    除了 UI 上的增强之外,knife4j 还提供了一些开箱即用的功能。

    比如:搜索 API 接口 (knife4j 版本>2.0.1 )

    图片

    再比如:导出离线文档

    通过 Knife4j 我们可以非常方便地导出 Swagger 文档 ,并且支持多种格式。

    • markdown:导出当前逻辑分组下所有接口的 Markdown 格式的文档
    • Html:导出当前逻辑分组下所有接口的 Html 格式的文档
    • Word:导出当前逻辑分组下所有接口的 Word 格式的文档(自 2.0.5 版本开始)
    • OpenAPI:导出当前逻辑分组下的原始 OpenAPI 的规范 json 结构(自 2.0.6 版本开始)
    • PDF:未实现

    以 HTML 格式导出的效果图如下。

    图片

    还等什么?快去试试吧!

  • 相关阅读:
    最大上升子序列
    vue的keep-alive组件
    对小程序的研究3
    对getBoundingClientRect属性的研究
    消除浮动的方式
    对微信小程序的研究2
    对小程序的研究1
    对props的研究
    对provide/inject的研究
    对calc()的研究
  • 原文地址:https://www.cnblogs.com/coder-wzr/p/swagger.html
Copyright © 2020-2023  润新知