What is Swagger
Swagger is a toolset driven by the OpenAPI specification that helps you design, build, document and consume REST APIs.
Advantages of Swagger:
-
Automatic generation of interface documents: Swagger can automatically scan interfaces and parameter annotations and generate interface development documents. During the debugging process, it can update the interface document in real time and provide an online interactive test UI, reducing the workload of maintaining the interface document.
-
Visual display of interface documents: The Swagger UI interface is intuitive and beautiful, which can improve the efficiency of interface collaboration. Simulation requests can be made directly in the document, or even exported as code call snippets in various languages such as curl, which is beneficial to front-end and back-end collaboration and communication.
-
Interface version management: Using Swagger can more conveniently manage the version of the API interface. Swagger configuration supports the simultaneous existence of multiple versions of API documents.
-
Other related functions: Swagger also provides many other useful functions, such as data type definition, route mapping, Mock service or validator, etc., making it not only a simple API document generation tool, but a complete API design and development tools.
SpringBoot uses annotations to integrate Swagger
- Import the swagger jar package under the pom.xml file
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- Add @EnableSwagger2Doc to the SpringBoot startup class to enable Swagger annotations
- Configure the SwaggerConfig configuration class, or configure Swagger information in the yml file
package com.yjh.config;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // controller所在的包
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注：http://spring.io/projects/spring-boot")
.termsOfServiceUrl("http://spring.io/projects/spring-boot")
// 优先使用yml文件的配置信息
.contact(new Contact("swagger", "http://spring.io/projects/spring-boot", ""))
.version("1.0")
.build();
}
}
yml configuration information
swagger:
enabled: true
title: API文档
description: Website
contact:
name: yjh
url: 联系网址
email: 联系人邮箱
#接口包扫描路径
base-package: com.yjh.controller
#需排除的接口路径
exclude-path: /error/**
-
Add @Api to the controller layer class marked with @contoller or @RestController, where tags, which means tag in Chinese, represents the name of this interface. If not written, Swagger will use the path name. In addition to tags, there is also an optional value, which also describes the interface name. Vaule is a first-level classification, usually named the module name or business name. Tags is a second-level classification, used to further divide the API interface under the same module. .
-
Start SpringBoot, visit http://localhost:9090/swagger-ui.html (remember to configure the port number), you can see the home page of Swagger2, view the configured API information, and complete the basic configuration of Swagger here.
