SpringBoot uses Swagger2
1. Introduce swagger dependency
<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>
2. Add swagger configuration class
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 createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//swagger文档扫描的包，这里扫描的是全部
//如果扫描指定包下的可以这样写
//.apis(RequestHandlerSelectors.basePackage("com.xxx.yyy.controller"))
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("标题")
.description("描述")
.version("版本")
.termsOfServiceUrl("公司网址")
.build();
}
}
3. Test Controller
@RestController
@RequestMapping("/test")
public class TestController {
@GetMapping("/test01")
public String test01(){
return "test01";
}
@GetMapping("/test02")
public String test02(){
return "test02";
}
@GetMapping("/test03")
public String test03(){
return "test03";
}
}
4. Test
After the project starts normally, the browser enters the URL
http://localhost:8100/swagger-ui.html#/
(the port here fills in the port of your own service, mine is 8100, and the default port is 8080)
Test Results
5. Annotation of swagger
The above is the basic use of swagger
, but swagger also provides some annotations, here are some common annotations
Api annotation
Documentation resource used to mark the current class as Swagger. It contains several commonly used attributes, which are described below.
• value: defines the name of the current interface document.
• description: Used to define the description of the current interface document.
@Api(value = "controller接口",description = "用户测试接口")
public class TestController {
ApiOperation annotation
@ApiOperation is used on the method of the interface, mainly used to annotate the request interface. It contains several commonly used attributes, which are described below.
• value: A short description of the API.
• note: detailed description of the API.
• hidden: If the value is true, it will be hidden in the document.
demo
@GetMapping("/test01")
@ApiOperation(value = "测试方法01",notes = "细节的描述，细节的测试",hidden = false)
public String test01(){
return "test01";
}
ApiImplicitParam, ApiImplicitParams annotations
Used on the API request method, a subset of @ApiImplicitParams is the @ApiImplicitParam annotation, where @ApiImplicitParam annotates common parameters.
• name: The name of the parameter.
• value: parameter value.
• required: If the value is true, it is a required field.
• defaultValue: The default value of the parameter.
• dataType: the type of data.
demo
@GetMapping("/test02")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "name",value = "测试姓名",required = false,defaultValue = "默认姓名李四"),
@ApiImplicitParam(name = "age",value = "测试年龄",required = false,dataType = "Integer",defaultValue = "200")
})
public String test02(String name,Integer age){
return "test02 姓名："+name+" 年龄:"+age;
}
ApiParam annotation
ApiParam is used for the parameters of the method, which contains the following common attributes.
• name: The name of the parameter.
• value: parameter value.
• required: If the value is true, it is a required field.
• defaultValue: The default value of the parameter.
• type: the type of the parameter.
• hidden: If the value is true, hide this parameter.
Similar to ApiImplicitParam and ApiImplicitParams annotations, no more details.
ApiResponse、ApiResponses注解
Both @ApiResponses and @ApiResponse are used together to return the HTTP status code. The value of @ApiResponses is a collection of @ApiResponse, and multiple @ApiResponse are separated by commas. Among them, the common parameters of @ApiResponse are as follows.
• code: HTTP status code.
• message: HTTP status information.
• responseHeaders: HTTP response headers.
demo
@GetMapping("/test03")
@ApiResponses(value = {
@ApiResponse(code = 200,message = "成功"),
@ApiResponse(code = 404,message = "异常")
})
public String test03(){
return "test03";
}
ResponseHeader annotation
If you need to set the response header, set @ResponseHeader to the responseHeaders parameter of @ApiResponse. @ResponseHeader provides the following parameters.
• name: Response header name.
• description: Description of the response header.
ApiModel, ApiModelProperty annotations
Set the entity class of the API response, used as the API return object. @ApiModel common parameters.
• value: Entity class name.
• description: entity class description.
Set the attributes of the API response entity, including common parameters.
• name: attribute name.
• value: attribute value.
demo
@ApiModel(value = "Student(学生类)",description = "记录学生个人信息")
public class Student {
public String name;
@ApiModelProperty(name = "age",value = "年龄")
public Integer age;
}
6. More
The summary of this article is rough.
For more detailed use, refer to swagger official website