Swagger-Bootstrap-UI is an open source project that provides beautiful, easy-to-use interface display and enhanced functions for Swagger. It provides better document display and interactive experience through customized styles and interactions, including beautified interface, interface testing tools, online debugging, document export and other functions.
For more advanced ones Knife4j, Knife4j is an
enhanced solution that integrates Swagger2 and OpenAPI3
. You can see the introduction on the Knife4j official website:
https://doc.xiaominfo.com/
Introduction and usage steps of Swagger-Bootstrap-UI:
This UI enhancement package mainly includes two core functions: documentation and online debugging
Document description: According to the Swagger specification, the description of the interface document is listed in detail, including interface address, type, request example, request parameter, response example, response parameter, response code and other information. Use swagger-bootstrap-ui to follow this document Description, the usage of this interface is clear at a glance.
Online debugging: Provides the powerful function of online interface joint debugging, automatically parses the current interface parameters, and also includes form verification. The calling parameters can return interface response content, headers, Curl request command instances, response time, response status code and other information to help developers Online debugging without having to use other testing tools to test whether the interface is correct, simple and powerful.
Introduce dependencies:
In your Spring Boot project's Maven or Gradle configuration file, add the dependency of Swagger-Bootstrap-UI.
Introduction of Jar package in Maven
Since it is an enhanced UI package of springfox-swagger, the basic functions still rely on Swagger. The jar package of springfox-swagger must be introduced.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
Then introduce the jar package of SwaggerBootstrapUi
<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'
Configure Swagger and Swagger-Bootstrap-UI:
In the Spring Boot project, configure Swagger's Docket and add the configuration of 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();
}
}
Start the application:
After starting the Spring Boot application, access the interface of Swagger-Bootstrap-UI. By default, the access path of Swagger-Bootstrap-UI is /doc.html, which can be accessed by entering it in the browser http://localhost:8080/doc.html .
On the Swagger-Bootstrap-UI interface, you can view and test the defined interface documents, including request and response parameters, interface descriptions, sample data, etc. You can also use online debugging tools to perform interface requests and export documents to PDF or Markdown format.
Please note that Swagger-Bootstrap-UI only provides a beautiful and easy-to-use interface display for Swagger, and it does not automatically generate interface documents. When configuring Swagger's Docket, you need to use Swagger's annotations to describe the interface and define parameters in detail so that Swagger-Bootstrap-UI can display and use it correctly.
In addition, you can learn more about configuring and using Swagger-Bootstrap-UI through the project page of Swagger-Bootstrap-UI
https://github.com/xiaoymin/Swagger-Bootstrap-UI .
Precautions
Springfox-swagger provides two Swagger interfaces by default, which require developers to release permissions (if using the shiro permission control framework, etc.). If you use the enhanced functions of SwaggerBootstrapUi, you also need to release the enhanced interface addresses. Therefore, the released permission interfaces include 3, namely:
/swagger-resources:Swagger's grouping interface
/v2/api-docs?group=groupName:The specific group instance interface of Swagger returns the Swagger information related to all interfaces under the group.
/v2/api-docs-ext?group=groupName:This interface is the enhanced interface address provided by SwaggerBootstrapUi. If you do not use UI enhancement, you can ignore this interface.
Shiro related configuration examples are as follows:
<!---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>
Solution to 404 error when accessing doc.html in SpringBoot
Implement SpringBoot's WebMvcConfigurer interface and add the relevant ResourceHandler. The code is as follows:
@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/");
}
}