I. Introdução
swagger-ui é um plug-in para produzir documentação de API no desenvolvimento Java, que é uma ponte para interfaces de depuração conjunta entre engenheiros de back-end e engenheiros de front-end. Os documentos gerados reduzem muita comunicação desnecessária e melhoram a eficiência do desenvolvimento e dos testes.
Em segundo lugar, o uso de swagger-ui
1. Introduzir dependência 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>
Versão: <swagger2.version>2.9.2</swagger2.version>
2. Adicione anotações à classe de inicialização do springboot
@EnableSwagger2
Indica que o documento está aberto
3. Adicione a anotação @ApiOperation ao método do controlador
como:
@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. Acesso através do projeto ip plus port plus swagger-ui.html#
http://ip:port/swagger-ui.html#
5. Descrição do documento
O documento apresenta o método de solicitação, endereço e finalidade da interface.
3. Anotações mais ricas
Além do uso simples acima, a API possui muitas anotações ricas
/**
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
*/
Por exemplo:
@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. Introdução ao swagger-ui
OpenAPI é uma especificação para escrever documentos de API, mas é muito problemático escrever manualmente documentos de especificação de OpenAPI. Swagger é um conjunto de ferramentas que implementa a especificação OpenAPI.
Simplifique o desenvolvimento de APIs para usuários, equipes e empresas com o código aberto Swagger e o conjunto de ferramentas profissionais. Descubra como o Swagger pode ajudá-lo a projetar e documentar suas APIs em grande escala.