Una aplicación web a menudo contiene una API para interactuar con ella. Al documentar sus API, sus clientes pueden comprender rápidamente cómo utilizar sus servicios. Si la API está cerrada desde el mundo exterior, entonces aún vale la pena tomarse el tiempo para la especificación; esto ayudará a sus nuevos colegas a comprender rápidamente el sistema.
Crear documentación a mano es un proceso tedioso. Swagger te ayudará a hacer este trabajo más fácil.
¿Qué es Swagger?
Swagger genera automáticamente documentación de API como json. Y el proyecto Springdoc creará una interfaz de usuario fácil de usar para la visualización. No solo podrá ver la documentación, sino también enviar solicitudes y recibir respuestas.
También es posible generar un cliente o servidor directamente de acuerdo con la especificación de la API Swagger, para ello se necesita un generador de código Swagger-Codegen .
Swagger adopta un enfoque declarativo, todo lo que amamos. Anotas métodos, parámetros, DTO.
Encontrará todos los ejemplos proporcionados aquí en mi repositorio .
Creando una API REST
Para documentar la API, comencemos por escribirla: smile: puedes pasar al siguiente capítulo para no perder el tiempo.
Agreguemos controladores primitivos y un DTO. La esencia de nuestro sistema es un programa de fidelización de usuarios.
, . .
DTO UserDto
— . , 3 : , , , ,
public class UserDto {
private String key;
private String name;
private Long points = 0L;
private Gender gender;
private LocalDateTime regDate = LocalDateTime.now();
public UserDto() {
}
public UserDto(String key, String name, Gender gender) {
this.key = key;
this.name = name;
this.gender = gender;
}
public static UserDto of(String key, String value, Gender gender) {
return new UserDto(key, value, gender);
}
// getters and setters
}
public enum Gender {
MAN, WOMAN
}
-, : UserController
, PointContoller
, SecretContoller
.
UserController
, .
@RestController
@RequestMapping("/api/user")
public class UserController {
private final Map<String, UserDto> repository;
public UserController(Map<String, UserDto> repository) {
this.repository = repository;
}
@PutMapping(produces = APPLICATION_JSON_VALUE)
public HttpStatus registerUser(@RequestBody UserDto userDto) {
repository.put(userDto.getKey(), userDto);
return HttpStatus.OK;
}
@PostMapping(produces = APPLICATION_JSON_VALUE)
public HttpStatus updateUser(@RequestBody UserDto userDto) {
if (!repository.containsKey(userDto.getKey())) return HttpStatus.NOT_FOUND;
repository.put(userDto.getKey(), userDto);
return HttpStatus.OK;
}
@GetMapping(value = "{key}", produces = APPLICATION_JSON_VALUE)
public ResponseEntity<UserDto> getSimpleDto(@PathVariable("key") String key) {
return ResponseEntity.ok(repository.get(key));
}
}
PointContoller
. .
@RestController
@RequestMapping("api/user/point")
public class PointController {
private final Map<String, UserDto> repository;
public PointController(Map<String, UserDto> repository) {
this.repository = repository;
}
@PostMapping("{key}")
public HttpStatus changePoints(
@PathVariable String key,
@RequestPart("point") Long point,
@RequestPart("type") String type
) {
final UserDto userDto = repository.get(key);
userDto.setPoints(
"plus".equalsIgnoreCase(type)
? userDto.getPoints() + point
: userDto.getPoints() - point
);
return HttpStatus.OK;
}
}
destroy
SecretContoller
.
@RestController
@RequestMapping("api/secret")
public class SecretController {
private final Map<String, UserDto> repository;
public SecretController(Map<String, UserDto> repository) {
this.repository = repository;
}
@GetMapping(value = "destroy")
public HttpStatus destroy() {
repository.clear();
return HttpStatus.OK;
}
}
Swagger
Swagger . .
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.1.6</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.2</version>
</dependency>
Swagger , . HTTP (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT).
: , .
, . , : localhost:8080/swagger-ui.html
. .
. .
SwaggerConfig
— .
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(
new Info()
.title("Example Swagger Api")
.version("1.0.0")
);
}
}
title
—version
— API
UI .
API, ,
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(
new Info()
.title("Loyalty System Api")
.version("1.0.0")
.contact(
new Contact()
.email("me@upagge.ru")
.url("https://uPagge.ru")
.name("Struchkov Mark")
)
);
}
, . @Tag
.
@Tag(name=" ", description=" ")
public class ControllerName {
// ... ... ... ... ...
}
, — SecretController
. @Hidden
.
@Hidden
@Tag(name = " ", description = " ")
public class SecretController {
// ... ... ... ... ...
}
Swagger. . API.
, .
@Operation
. :
summary
— .description
— .
@Operation(
summary = " ",
description = " "
)
public HttpStatus registerUser(@RequestBody UserDto userDto) {
// ... ... ... ... ...
}
Parameter
, .
public HttpStatus changePoints(
@PathVariable @Parameter(description = " ") String key,
@RequestPart("point") @Parameter(description = " ") Long point,
@RequestPart("type") @Parameter(description = " ") TypeOperation type
) {
// ... ... ... ... ...
}
required
. .
DTO
, . - DTO @Schema
@Schema(description = " ")
public class UserDto {
@Schema(description = "")
private String key;
// ... ... ... ... ...
}
, : enum, . DTO , .
@Schema(description = "", example = "A-124523")
:
, . . swagger Schema.AccessMode.READ_ONLY
:
public class UserDto {
@Schema(accessMode = Schema.AccessMode.READ_ONLY)
private String key;
...
}
PointController
. , .
public HttpStatus changePoints(
// ... ... ... ... ...
@RequestPart("point") @Min(0) @Parameter(description = " ") Long point,
// ... ... ... ... ...
) {
// ... ... ... ... ...
}
. point
minimum: 0
.
.
, API .
, .