Eine Webanwendung enthält häufig eine API zur Interaktion mit ihr. Durch die Dokumentation Ihrer APIs können Ihre Kunden schnell verstehen, wie Sie Ihre Dienste nutzen. Wenn die API von außen geschlossen ist, lohnt es sich dennoch, sich die Zeit für die Spezifikation zu nehmen. Dies hilft Ihren neuen Kollegen, das System schnell zu verstehen.
Das Erstellen von Dokumentationen von Hand ist ein langwieriger Prozess. Swagger wird Ihnen helfen, diese Arbeit zu erleichtern.
Was ist Swagger?
Swagger generiert automatisch eine API-Dokumentation als json. Das Springdoc-Projekt erstellt eine benutzerfreundliche Benutzeroberfläche für die Visualisierung. Sie können nicht nur die Dokumentation anzeigen, sondern auch Anfragen senden und Antworten empfangen.
Es ist auch möglich, einen Client oder Server direkt gemäß der Swagger-API-Spezifikation zu generieren. Dazu benötigen Sie einen Swagger-Codegen- Codegenerator .
Swagger verfolgt einen deklarativen Ansatz, alles, was wir lieben. Sie kommentieren Methoden, Parameter und DTOs.
Alle Beispiele finden Sie hier in meinem Repository .
Erstellen einer REST-API
Um die API zu dokumentieren, schreiben wir sie zuerst: smile: Sie können mit dem nächsten Kapitel fortfahren, damit Sie keine Zeit verschwenden.
Fügen wir primitive Controller und ein DTO hinzu. Die Essenz unseres Systems ist ein Benutzerbindungsprogramm.
, . .
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 .
, .