Webアプリケーションには、多くの場合、それと対話するためのAPIが含まれています。APIを文書化することで、顧客はサービスの使用方法をすばやく理解できます。APIが外部から閉じられている場合でも、仕様に時間をかける価値があります。これは、新しい同僚がシステムをすばやく理解するのに役立ちます。
手作業でドキュメントを作成するのは面倒なプロセスです。Swaggerは、この作業を簡単にするのに役立ちます。
Swaggerとは何ですか？
Swaggerは、APIドキュメントをjsonとして自動的に生成します。また、Springdocプロジェクトは、視覚化のためのユーザーフレンドリーなUIを作成します。ドキュメントを表示できるだけでなく、リクエストを送信したり、レスポンスを受信したりすることもできます。
Swagger API仕様に従ってクライアントまたはサーバーを直接生成することもできます。このためには、Swagger-Codegenコードジェネレーターが必要です。
Swaggerは、私たちが愛するすべてのものを宣言的なアプローチで採用しています。メソッド、パラメーター、DTOに注釈を付けます。
ここで提供されているすべての例は、私のリポジトリにあります。
RESTAPIの作成
APIを文書化するために、それを書くことから始めましょう：smile：時間を無駄にしないように、次の章に進むことができます。
プリミティブコントローラーと1つのDTOを追加しましょう。私たちのシステムの本質は、ユーザーロイヤルティプログラムです。
, . .
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 .
, .