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", "admin@demo.com.cn"))
                // 描述
                .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", "admin@demo.com.cn"))
                // 描述
                .description(description)
                // 定义版本号
                .version("1.0").build();
    }

}

如此后即可测试认证后的接口。

PS：如有错误，或者搭建过程中遇到问题，请在评论中评论，看到后会第一时间更正。