JAVA开发环境接口swagger-ui使用总结

一、前言

swagger-ui是java开发中生产api说明文档的插件，这是后端工程师和前端工程师联调接口的桥梁。生成的文档就减少了很多没必要的沟通提高开发和测试效率。

二、 swagger-ui的使用

1、引入maven依赖

		<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、在springboot启动类上加上注解

@EnableSwagger2

表示开启文档

3、在controller的方法加上注解 @ApiOperation

如：

@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、通过项目ip加端口加上swagger-ui.html#访问

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

5、文档说明

 文档介绍了接口的请求方式，地址和用途。

三、更加丰富的注解

除了上面简单的使用，api还有很多丰富的注解

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

如示例：

@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){}

四、swagger-ui介绍

OpenAPI是一个编写API文档的规范，然而如果手动去编写OpenAPI规范的文档，是非常麻烦的。而Swagger就是一个实现了OpenAPI规范的工具集。

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.