SpringBoot + Swagger + swagger-bootstrap-ui制作在线API文档

SpringBoot + Swagger + swagger-bootstrap-ui制作在线API文档

Swagger这个框架我想大部分人多多少少有听说或者接触过，这个框架的宗旨在于简化后台开发者写doc api接口时间，在开发过程中，只要加入一些注解以及注释，就能被编译成一个网页，访问网页后的在线接口文档，都是配置好的，并且有个按钮，可以提供前端调试接口，查看返回数据。

可以说这个框架挺好的，入参的参数，参数类型，是否非空，请求头等等；不足的地方在于Swagger提供的Swagger-UI样式是真的不好看。。。这个是值得吐槽的地方。

也是因为一个东西的不足，自然会有人去完善，swagger-bootstrap-ui的出现就是为了弥补这个样式的不足，与原生Swagger-UI毫无冲突；这个框架主要优化了原生框架页面样式的排版，加入了bootstrap样式元素，看着更舒服。

1. 引入pom文件

		
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.8.7
        

头两个引入Swagger框架没问题，重要的是引入最后的UI框架，这个要和Swagger一起

2. 加入配置类

import io.swagger.annotations.Api;
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.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置类
 * @author 如漩涡
 */
@Configuration
@EnableSwagger2
public class Swagger {
    /**
     * apis这个方法说明一下，这个方法主要是扫描带有注解“@Api”的类
     */
    @Bean
    public Docket creatRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API访问路径：/doc.html
     * title: 模块名称
     * contact：创建人信息
     * description: 模块描述
     * version:版本
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后台API接口文档")
                .contact(new Contact("如漩涡", "xx", "**"))
                .description("后台端")
                .version("0.0.1")
                .build();
    }
}

最好把这个类与启动类同级

创建Docket对象时，apis这个方法比较重要，是制定要生成接口文档在哪个位置，有两个方法，一个是RequestHandlerSelectors.withClassAnnotation，以上代码块中的这个方法，这个方法意思是扫描带有@Api这个注解的类生成文档，还有一个方法是RequestHandlerSelectors.basePackage，这个需要就需要制定目录了，内置传参是String类型，例如com.xx.xx.web，这个包地址是放置controller的，制定扫描。

另外还有一个配置类，是控制整个web配置的类，需要继承WebMvcConfigurerAdapter

import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import org.springframework.context.annotation.Configuration;

@Configuration
public class WebMvcConfiguration extends WebMvcConfigurerAdapter {
    /**
     * 资源映射
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
    }

    /**
     * 添加拦截器
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry){
        registry.addInterceptor(apiInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")
                .excludePathPatterns("/error");
    }
    /**
     * 注入拦截器(自定义)
     * @return
     */
    @Bean
    public ApiInterceptor apiInterceptor(){
        return new ApiInterceptor();
    }

}

重要的代码块在于addResourceHandlers这个重载的方法，在这个方法里的内容是将Swagger-UI的网页地址映射出去，避免被资源拦截。

另外如果项目中添加了拦截器的话，需要在拦截器排除掉Swagger-UI的请求，不然无法访问到，代码块在addInterceptors这个方法中。

3. 注解的使用

在这里我随便拿出一个controller类来做示范

**
 * 项目管理controller
 *
 * @author 如漩涡
 */
@RestController
@RequestMapping("/project")
@Api(tags = {"项目管理"}, description = "相关接口")
public class OaProjectController{
    @Autowired
    private OaProjectService projectService;
    
    @ApiOperation(value = "表单列表", notes = "查询")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "projectType", value = "项目类型(1：上线；2：未上线)", required = false, dataType = "Integer"),
            @ApiImplicitParam(paramType = "query", name = "projectStatus", value = "项目状态(1：进行中；2：暂停；3：已完结/废弃)", required = false, dataType = "Integer"),
            @ApiImplicitParam(paramType = "query", name = "departmentId", value = "出品方ID", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "name", value = "项目名称", required = false, dataType = "String")
    })
    @GetMapping("/list")
    public Result list(@RequestParam(required = false) Integer projectType,
                       @RequestParam(required = false) Integer projectStatus,
                       @RequestParam(required = false) String departmentId,
                       @RequestParam(required = false) String name){
        
        List<OaProjectDTO> list = projectService.list(projectType, projectStatus, departmentId, name);
        
        return ResultUtil.success(list);
    }
}

@Api：这个注解在前面说过了，一方面用于配置类扫描，另一方面为生成后的文档产生标题；

@ApiOperation：注释在方法上，为方法生成备注作用；

@ApiImplicitParams：参数的注解，内置还需要ApiImplicitParam一起使用，两个是一个组合；

还有一些其他注解，可以参考官网

4. 访问网页

准备工作都做好以后，项目启动，访问IP：端口号/doc.html即可