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 格式導出的效果圖如下。

圖片

還等什么?快去試試吧!


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM