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

以你之姓@ 2024-04-18 19:22 70阅读 0赞

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

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

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

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

### 1. 引入pom文件 ###

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.8.7</version>
            </dependency>

头两个引入`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. 访问网页 ###