JAVA development environment interface swagger-ui use summary

I. Introduction

swagger-ui is a plug-in for producing api documentation in java development, which is a bridge for joint debugging interfaces between back-end engineers and front-end engineers. The generated documents reduce a lot of unnecessary communication and improve the efficiency of development and testing.

Second, the use of swagger-ui

1. Introduce maven dependency

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${swagger2.version}</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${swagger2.version}</version>
		</dependency>

版本：  <swagger2.version>2.9.2</swagger2.version>

2. Add annotations to the springboot startup class

@EnableSwagger2

Indicates that the document is opened

3. Add annotation @ApiOperation to the controller method

like:

@RestController
@RequestMapping("tmpMUser")
public class TmpMUserController {

	@Autowired
	private TmpMUserService tmpMUserService;

	@ApiOperation(value = "解密酒店手机号", httpMethod = "POST", response = ResponseData.class, notes = "解密酒店手机号")
	@PostMapping("updateOne")
	public ResponseData<String> updateOne(Map<String, Object> param) {
		try {
			tmpMUserService.updateOne();
			return ResponseData.success("成功");
		} catch (Exception e) {
			e.printStackTrace();
		}
		return ResponseData.error();
	}

}

4. Access through project ip plus port plus swagger-ui.html#

http://ip:port/swagger-ui.html#

5. Document description

 The document introduces the request method, address and purpose of the interface.

3. Richer annotations

In addition to the simple use above, the api has many rich annotations

/**
 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数
 */

For example:

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false) 
                       @RequestParam(value = "name", required = false) 
                       String account,
                       @ApiParam(name = "pass", value = "密码", required = false) 
                       @RequestParam(value = "pass", required = false) 
                       String password){}

//或以实体类为参数：
@ResponseBody 
@PostMapping(value="/login") 
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在") 
public UserModel login(@ApiParam(name = "model", value = "用户信息Model") UserModel model){}

4. Introduction to swagger-ui

 

OpenAPI is a specification for writing API documents. However, it is very troublesome to manually write OpenAPI specification documents. Swagger is a toolset that implements the OpenAPI specification.

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.