技術(shù)

語言 : Java

框架 : SpringBoot + Swagger

工具 : Maven + IDEA + PostMan + Swagger

GitHub項目地址 : Swagger

說明

# 絲襪哥 `Swagger` 是研發(fā)的好幫手,可以減少很多后端和前端的溝通的成本,甚至在很多高級的公司,還能夠減少后端和測試人員的溝通成本.所以只需要一個項目采用了SpringBoot框架,絲襪哥 `Swagger` 幾乎就是必須要選擇的組件
# 在之前 Swagger的工具的starter是百花齊放,而現(xiàn)在,終于有了官方的啟動工具類,接下來就是快速食用工具

pom依賴

<!--導入 絲襪哥 (Swagger)-->
<dependency>
<groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!--配置jar包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-oas</artifactId>
    <version>3.0.0</version>
</dependency>

瀏覽器訪問地址

http://localhost:8181/springboot-swagger/swagger-ui/

有網(wǎng)址說需要添加 @EnableOpenApi 注解,但其實是不需要的

接口文檔的首頁截圖

關于整合認證(權(quán)限)插件

如果用到了Spring Security 權(quán)限的控制組件,記得要加入白名單

//例如
String[] SWAGGER_WHITELIST = {
        "/swagger-ui.html",
        "/swagger-ui/*",
        "/swagger-resources/**",
        "/v2/api-docs",
        "/v3/api-docs",
        "/webjars/**"
};
httpSecurity.cors()
        .antMatchers(SWAGGER_WHITELIST).permitAll();

但是在某些時候,我們使用了 JWT 這樣的中間件 , 就需要在請求接口的時候,在 Header 中構(gòu)造一個token,Swagger 也支持了他們

//基礎的配置

/**
 * SwaggerConfig
 * Swagger 的實體類
 * @author HCY
 * @since 2020/10/15
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //開啟個人信息
                .apiInfo(apiInfo())
                .select()
                .build()
                //每一個請求都可以添加header
                .globalRequestParameters(globalRequestParameters())
                //開啟全局的token
                .securitySchemes(security());

    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //api文本
                .title("曉尋遙 api")
                //說明
                .description("更多請咨詢曉尋遙")
                //用戶名 + 網(wǎng)址 + 郵箱
                .contact(new Contact("曉尋遙" ,
                        "https://github.com/xiaoxunyao" ,
                        "2414776185@qq.com"))
                //版本
                .version("1.0")
                //運行
                .build();
    }
}

第一種,通過全局的Auth認證方式

private List<SecurityScheme> security() {
        ApiKey apiKey = new ApiKey("Token", "Token", "header");
        return Collections.singletonList(apiKey);
}

全局token

第二種, 每個請求一個token , 適用于 快速過期的JWT模式

private List<RequestParameter> globalRequestParameters() {
        RequestParameterBuilder parameterBuilder = new RequestParameterBuilder()
                //每次請求加載header
                .in(ParameterType.HEADER)
                //頭標簽
                .name("Token")
                .required(false)
                .query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)));
        return Collections.singletonList(parameterBuilder.build());
}

每個請求都帶上token

結(jié)束

# 不用自己寫接口文檔了,讓前端的小伙伴看了一下 絲襪哥 `Swagger` ,小伙伴說再也不想看我寫的接口文檔了,我就明白了,用它用它.
# nice