Swagger-Bootstrap-UI

news2024/12/27 3:45:41

Swagger-Bootstrap-UI 是一个为 Swagger 提供美观、易用的界面展示和增强功能的开源项目。它通过自定义样式和交互，提供了更好的文档展示和交互体验，包括美化的界面、接口测试工具、在线调试、文档导出等功能。

更高阶的有Knife4j,Knife4j是一个集Swagger2 和 OpenAPI3
为一体的增强解决方案
可以看Knife4j官网介绍：
https://doc.xiaominfo.com/

Swagger-Bootstrap-UI 的介绍和使用步骤：

该UI增强包主要包括两大核心功能：文档说明和在线调试

文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。

在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。
在这里插入图片描述

引入依赖：

在您的 Spring Boot 项目的 Maven 或 Gradle 配置文件中，添加 Swagger-Bootstrap-UI 的依赖项。

Maven中引入Jar包
由于是springfox-swagger的增强UI包,所以基础功能依然依赖Swagger,springfox-swagger的jar包必须引入

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
</dependency>

然后引入SwaggerBootstrapUi的jar包

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>${lastVersion}</version>
</dependency>

Gradle:

implementation 'com.github.xiaoymin:swagger-bootstrap-ui:1.9.6'

配置 Swagger 和 Swagger-Bootstrap-UI：

在 Spring Boot 项目中，配置 Swagger 的 Docket，并添加 Swagger-Bootstrap-UI 的配置。

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.package.name"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Your API Title")
                .description("Your API Description")
                .version("1.0.0")
                .build();
    }
}

启动应用程序：

启动 Spring Boot 应用程序后，访问 Swagger-Bootstrap-UI 的界面。默认情况下，Swagger-Bootstrap-UI 的访问路径为 /doc.html，可以在浏览器中输入 http://localhost:8080/doc.html 进行访问。

在 Swagger-Bootstrap-UI 界面上，您可以查看和测试已定义的接口文档，包括请求和响应参数、接口说明、示例数据等。您还可以使用在线调试工具执行接口请求，并将文档导出为 PDF 或 Markdown 格式。

请注意，Swagger-Bootstrap-UI 仅为 Swagger 提供了一个美观、易用的界面展示，它并不会自动生成接口文档。在配置 Swagger 的 Docket 时，您需要使用 Swagger 的注解对接口进行详细描述和参数定义，以便 Swagger-Bootstrap-UI 能够正确展示和使用。

另外，您可以通过 Swagger-Bootstrap-UI 的项目页面
https://github.com/xiaoymin/Swagger-Bootstrap-UI了解更多关于配置和使用 Swagger-Bootstrap-UI 的信息和功能。

注意事项

Springfox-swagger默认提供了两个Swagger接口,需要开发者放开权限(如果使用shiro权限控制框架等)，如果使用SwaggerBootstrapUi的增强功能,还需放开增强接口地址,所以，放开的权限接口包括3个，分别是：

/swagger-resources:Swagger的分组接口

/v2/api-docs?group=groupName:Swagger的具体分组实例接口,返回该分组下所有接口相关的Swagger信息

/v2/api-docs-ext?group=groupName:该接口是SwaggerBootstrapUi提供的增强接口地址,如不使用UI增强,则可以忽略该接口

Shiro的相关配置实例如下：

<!---other settings-->
<property name="filterChainDefinitions">    
    <value>     
        /swagger-resources = anon
        /v2/api-docs = anon
        /v2/api-docs-ext = anon
        /doc.html = anon
        /webjars/** = anon
        
        //others....
    </value>    
</property>

SpringBoot中访问doc.html报404的解决办法

实现SpringBoot的WebMvcConfigurer接口，添加相关的ResourceHandler,代码如下：

@SpringBootApplication
@ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
public class SwaggerBootstrapUiDemoApplication  implements WebMvcConfigurer{

	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}
}