Une application Web contient souvent une API pour interagir avec elle. En documentant vos API, vos clients peuvent rapidement comprendre comment utiliser vos services. Si l'API est fermée du monde extérieur, il vaut toujours la peine de prendre le temps de la spécification - cela aidera vos nouveaux collègues à comprendre rapidement le système.
Créer une documentation à la main est un processus fastidieux. Swagger vous aidera à rendre ce travail plus facile.
Qu'est-ce que Swagger?
Swagger génère automatiquement la documentation de l'API en tant que json. Et le projet Springdoc créera une interface utilisateur conviviale pour la visualisation. Vous pourrez non seulement consulter la documentation, mais également envoyer des demandes et recevoir des réponses.
Il est également possible de générer un client ou un serveur directement selon la spécification de l'API Swagger, pour cela vous avez besoin d'un générateur de code Swagger-Codegen .
Swagger adopte une approche déclarative, tout ce que nous aimons. Vous annotez des méthodes, des paramètres, des DTO.
Vous trouverez tous les exemples fournis ici dans mon référentiel .
Créer une API REST
Pour documenter l'API, commençons par l'écrire: smile: Vous pouvez passer au chapitre suivant pour ne pas perdre de temps.
Ajoutons des contrôleurs primitifs et un DTO. L'essence de notre système est un programme de fidélisation des utilisateurs.
, . .
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 .
, .