Swagger 官方 Starter 配上這個增強方案是真的香！

1. SpringBoot 項目中如何使用？

2. Spring Security 項目中如何使用？

3. 使用 knife4j 增強 Swagger

SpringBoot 項目中如何使用？

<dependency>
????<groupId>io.springfoxgroupId>
????<artifactId>springfox-boot-starterartifactId>
????<version>3.0.0version>
dependency>

Spring Security 項目中如何使用？

????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()
??????????......
????}

1. 登錄后自動為請求添加 token。

2. 為請求的 Header 添加一個認證參數(shù)，每次請求的時候，我們需要手動輸入 token。

登錄后自動為請求添加 token

/**
?*?@author?shuang.kou
?*?@description?swagger?相關(guān)配置
?*/
@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?securitySchemes()?{
????????return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));
????}

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

????List?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 添加一個認證參數(shù)

@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?securitySchemes()?{
????????return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));
????}

????private?List?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

1. YApi?：YApi 是一個可本地部署的、打通前后端及 QA 的、可視化的接口管理平臺?？梢詭椭覀冏?swagger 頁面的體驗更加友好，目前很多大公司都在使用這個開源工具。項目地址：https://github.com/YMFE/yapi?。
2. Knife4j?：Swagger 生成 Api 文檔的增強解決方案，前身是 swagger-bootstrap-ui 。官方文檔：https://xiaoym.gitee.io/knife4j/documentation/ 。

<dependency>
????<groupId>com.github.xiaoymingroupId>
????<artifactId>knife4j-spring-boot-starterartifactId>
????<version>3.0.2version>
dependency>

• markdown：導(dǎo)出當(dāng)前邏輯分組下所有接口的 Markdown 格式的文檔
• Html：導(dǎo)出當(dāng)前邏輯分組下所有接口的 Html 格式的文檔
• Word:導(dǎo)出當(dāng)前邏輯分組下所有接口的 Word 格式的文檔(自 2.0.5 版本開始)
• OpenAPI:導(dǎo)出當(dāng)前邏輯分組下的原始 OpenAPI 的規(guī)范 json 結(jié)構(gòu)(自 2.0.6 版本開始)
• PDF:未實現(xiàn)