swagger describes how to use it
1. Introduction to swagger
1. It is a standard and complete framework for you to better write API documents.
2. Provides description, production, consumption, and visualization of restful web services.
3. It is a formal specification supported by a large set of tools. This collection covers everything from the end-user interface, the underlying code base to business API management.
2 add dependency
2.1 use of third party dependencies
1. Add the third-party swagger dependency in the pom file
<dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.7.0.RELEASE</version> </dependency>
2. Add the @ EnableSwagger2Doc annotation on the startup of the SpringBoot project, and you can use it directly.
3, https://github.com/SpringForAll/spring-boot-starter-swagger This is the swagger dependent implementation project on GitHub, which is explained in detail.
2.2 use of official reliance
1. Add swagger related dependencies in pom.xml file
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
The first is the package obtained by API, and the second is an official ui interface. This interface can be customized and is official by default. We need to focus on security issues and ui routing settings.
2.2.1 swagger configuration
Special attention should be paid to swagger scan base package, which is the configuration of scanning annotations, that is, the location of your API interface.
package com.example.demo.config;
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.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)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("utilize swagger structure api file")
.description("Simple use swagger2")
.version("1.0")
.build();
}
}
3. Introduction to basic notes of swagger
swagger generates interface documents through annotations, including interface name, request method, parameters, returned information, etc.
| annotation | effect |
|---|---|
| @Api | Modifies the entire class to describe the role of the Controller |
| @ApiOperation | Describe a method or interface of a class |
| @ApiParam | Single parameter description |
| @ApiModel | Use object entities as input parameters |
| @ApiProperty | When receiving entity parameters with an object, a field describing the object |
| @ApiResponse | One description of the HTTP response |
| @ApiResponses | Overall description of HTTP response |
| @ApiIgnore | Use this annotation to ignore this API |
| @ApiError | Information returned when an error occurs |
| @ApiImplicitParam | A request parameter |
| @ApiImplicitParams | Multiple request parameters |
3.1 @Api modifies the entire class to describe the role of Controller
3.2 @ApiOperation
Used to describe a method or interface
Parameter forms that can be added: @ ApiOperation(value = "interface description", httpMethod = "interface request method", response = "interface return parameter type", notes = "interface release description")
example
@RequestMapping(value = "/hello",method = {RequestMethod.GET,RequestMethod.POST})
@ApiOperation(value = "Entry request",notes = "Request home page",httpMethod = "GET",response = String.class)
public String testHello(@RequestParam("username") String username,int id){
System.out.println("username:"+username+"==id:"+id);
return "ok:"+username;
}
3.3 @ApiParam single parameter description
@ApiParam(required = "parameter required", name = "parameter name", value = "parameter specific description", dateType = "variable type", paramType = "request method")
@RequestMapping("/swagger")
@ResponseBody
@ApiOperation(value = "Get user information according to user name",notes = "Query records in the database",httpMethod = "POST",response = String.class)
@ApiImplicitParam(name = "userName",value = "user name",required = true,dataType = "String",paramType = "query")
public String getUserInfo(String userName) {
return "1234";
}
3.4 @ApiImplicitParam a request parameter
@ApiImplicitParam(required = "parameter required", name = "parameter name", value = "parameter specific description", dateType = "variable type", paramType = "request method")
@RequestMapping("/swagger")
@ApiOperation(value = "Get user information according to user name",notes = "Query records in the database",httpMethod = "POST",response = String.class)
@ApiImplicitParam(name = "userName",value = "user name",required = true,dataType = "String",paramType = "query")
public String getUserInfo(String userName) {
return "1234";
}
3.5 @ApiImplicitParams multiple request parameters
The parameter is consistent with @ ApiImplicitParam, except that multiple parameters can be added to this annotation
@RequestMapping(value = "/getuserinfobynickname",method = {RequestMethod.POST,RequestMethod.GET})
@ApiOperation(value = "Get user information according to user nickname",notes = "Query records in the database")
@ApiImplicitParams({
@ApiImplicitParam(name = "nickName",value = "User's nickname",paramType = "query",dataType = "String",required = true),
@ApiImplicitParam(name = "id",value = "User's ID",paramType = "query",dataType = "int",required = true)
})
public String getUserInfoByNickName(String nickName, int id) {
System.out.println("id:"+id+"--nickName:"+nickName);
return "1234";
}
It can be tested directly
3.6 corresponding entity Description:
package com.example.demo.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "User registered entity")
public class Register {
@ApiModelProperty(name = "userName",notes = "user name",dataType = "String",required = true)
private String userName;
@ApiModelProperty(name = "nickName",notes = "User nickname",dataType = "String",required = true)
private String nickName;
@ApiModelProperty(name = "age",notes = "User age",dataType = "int",required = true)
private int age;
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
public String getNickName() {
return nickName;
}
public void setNickName(String nickName) {
this.nickName = nickName;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
@Override
public String toString() {
return "Register{" +
"userName='" + userName + '\'' +
", nickName='" + nickName + '\'' +
", age=" + age +
'}';
}
}
appendix
IndexController code
package com.example.demo.controller;
import com.example.demo.pojo.Register;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
@RestController
@Api(value="user controller",description="Entrance interface",tags={"Entrance interface"})
public class IndexController {
// @RequestMapping(value = "/userregister",method = {RequestMethod.GET,RequestMethod.POST})
//@RequestMapping(value = "/userregister",method = {RequestMethod.POST})
// @ResponseBody
// @ApiOperation(value = "register",notes = "registered entity class")
// @RequestMapping(value = "/hello",method = {RequestMethod.GET,RequestMethod.POST})
// @ApiOperation(value = "entry request", notes = "request first page", httpMethod = "GET",response = String.class)
// @RequestBody
// @ApiImplicitParam(name = "username",value = "requester name", required = true,dataType="String",paramType="query")
@RequestMapping(value = "/hello",method = {RequestMethod.GET,RequestMethod.POST})
@ApiOperation(value = "Entry request",notes = "Request home page",httpMethod = "GET",response = String.class)
@ApiImplicitParam(name = "username",value = "Name of requester",required = true,dataType="String",paramType="query")
public String testHello(@RequestParam("username") String username,int id){
System.out.println("username:"+username+"==id:"+id);
return "ok:"+username;
}
@RequestMapping("/swagger")
@ResponseBody
@ApiOperation(value = "Get user information according to user name",notes = "Query records in the database",httpMethod = "POST",response = String.class)
@ApiImplicitParam(name = "userName",value = "user name",required = true,dataType = "String",paramType = "query")
public String getUserInfo(String userName) {
return "1234";
}
@RequestMapping(value = "/getuserinfobynickname",method = {RequestMethod.POST,RequestMethod.GET})
@ResponseBody
@ApiOperation(value = "Get user information according to user nickname",notes = "Query records in the database")
@ApiImplicitParams({
@ApiImplicitParam(name = "nickName",value = "User's nickname",paramType = "query",dataType = "String",required = true),
@ApiImplicitParam(name = "id",value = "User's ID",paramType = "query",dataType = "int",required = true)
})
public String getUserInfoByNickName(String nickName, int id) {
System.out.println("id:"+id+"--nickName:"+nickName);
return "1234";
}
@RequestMapping(value = "/getuserinfobyid",method = {RequestMethod.POST,RequestMethod.POST})
@ResponseBody
@ApiOperation(value = "According to user id Get user information",notes = "Query records in the database",httpMethod = "POST")
public String getUserInfoById(@ApiParam(name = "nickName",value = "User's nickname",required = true,defaultValue = "123-Default value")
String nickName,
@ApiParam(name = "id",value = "user ID",required = true)
Integer id) {
System.out.println("id:"+id+"--nickName:"+nickName);
return "1234";
}
@RequestMapping(value = "/userregister",method = {RequestMethod.GET,RequestMethod.POST})
//@RequestMapping(value = "/userregister",method = {RequestMethod.POST})
@ResponseBody
@ApiOperation(value = "register",notes = "Registered entity class")
public Register userRegister(Register register) {
System.out.println(register.toString());
return register;
}
}