springfox-swagger2開發

Swagger 簡介

官方介紹：Swagger提供了用於生成，可視化和維護API文檔的一系列解決方案，從而使API文檔不再需要人工操作。

創建項目

本文是基於springboot的maven工程進行搭建使用，因此首先創建一個spring的工程
注意：本文章中的例子僅作參考，手敲代碼，不保障能CV運行

引入依賴

創建完成後，引入兩個swagger依賴jar

<dependency>
	<groupId>io.springfox</groupId>
   	<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
</dependency>

創建swagger2相關類

• swagger2 配置類，和應用啓動類放在同級下

@Configuration
@EnableSwagger2
public class Swagger2 {
    
    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/api/AAA/**")).build().groupName("A").pathMapping("/")
                .apiInfo(apiInfo("A 接口文檔", "歡迎訪問 A 接口文檔，這裏是描述信息"));
    }
    /**
     * @Description: 構建 api文檔的信息
     */
    private ApiInfo apiInfo(String title, String description) {
        return new ApiInfoBuilder()
                // 設置頁面標題
                .title(title)
                // 設置聯繫人
                .contact(new Contact("username", "https://www.demo.com", "[email protected]"))
                // 描述
                .description(description)
                // 定義版本號
                .version("1.0").build();
    }

}

• Dao 類
• 實體類
• service類

上面的三個類，和其他的時候寫法一樣，沒有什麼變化，這裏不佔篇幅了，不寫也行，直接controller類接收數據，然後返回數據即可

• controller

@Api(value = "AAA|aaa接口類")
public class AAA {
	@ApiOperation(value="aaa", notes="aaa")
    @ApiImplicitParam(paramType="query", name = "aaaID", value = "ID", required = true, dataType = "String")
    public ResultDto<List<String>> aaa(String aaaID){
    	List<String> list = new ArrayList<String>();
    	list.add("aaa");
    	list.add("bbb");
     	return new ResultDto<List<String>>(list);
    }
}

PS :文中使用的是springfox-swagger2的jar ，因此controller中也可以不進行Api相關注釋的編寫，因爲Springfox是集成了Spring與Swagger，幫助開發人員自動生成controller類的對應API文檔，但相對的也就導致文檔不是太友好，因此我們可以針對的有選擇去寫註釋來進行文檔的優化，或者不寫註釋節省開發時間。
不需要生成API文檔的可以通過增加註釋進行忽略

 @ApiIgnore

到這裏，我們就可以通過訪問 http://localhost:8080/swagger-ui2.html
但有些已存在的項目可能會因爲原有的配置或者一些認證的問題導致無法訪問
這裏提供幾個思路進行解決，問題就不描述了。

• 切換瀏覽器/清空瀏覽器緩存的方式
• 查看對應的靜態資源文件是否加載
• 打開shiro或者oauth之類的認證框架對於swagger的請求的限制

 @Override
        public void configure(HttpSecurity hs) throws Exception {
hs.exceptionHandling()
                    .authenticationEntryPoint((request, response, authException) -> response
                            .sendError(HttpServletResponse.SC_UNAUTHORIZED))
                    .and().csrf().disable().addFilterBefore(corsFilter, UsernamePasswordAuthenticationFilter.class)
                    .headers().frameOptions().disable()
                    .and().sessionManagement()
                    .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                    //增加部分 start
                    .and().authorizeRequests().antMatchers("/v2/api-docs/**").permitAll()
                    .antMatchers("/swagger-resources/configuration/ui").permitAll();
                    //增加部分 end  注意分號

• 打開WebSecurityConfigurer 配置類對於swagger的請求的限制

@Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring()
        //增加部分 start
            .antMatchers(HttpMethod.OPTIONS, "/**").antMatchers("/v2/**")
            //增加部分 end  注意分號

對於權限認證類的工程
需要在swagger2的配置類加上權限認證的配置
完整的 swagger 配置類如下

package cn.com.yusys.yusp.admin;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
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;

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

@Configuration
@EnableSwagger2
public class Swagger2 {
   
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
               .paths(PathSelectors.ant("/api/AAA/**")).build().groupName("A").pathMapping("/")
                .apiInfo(apiInfo("A 接口文檔", "歡迎訪問 A 接口文檔，這裏是描述信息")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList();
        // 這裏要注意 不同的認證 Key 不一樣，可能需要針對自己的訪問認證 參數進行調整
        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;
    }

    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;
    }
    /**
     * @Description: 構建 api文檔的信息
     */
    private ApiInfo apiInfo(String title, String description) {
        return new ApiInfoBuilder()
                // 設置頁面標題
                .title(title)
                // 設置聯繫人
                .contact(new Contact("username", "https://www.demo.com", "[email protected]"))
                // 描述
                .description(description)
                // 定義版本號
                .version("1.0").build();
    }

}

如此後即可測試認證後的接口。

PS：如有錯誤，或者搭建過程中遇到問題，請在評論中評論，看到後會第一時間更正。