[SpringDoc] annotation

API docs를 편하게 자동으로 생성해주는 것이 OpenAPI3.0 spec을 이용하여 구현한 SpringDoc이다. API Docs 작성을 도와주는 건 Springfox Swagger와 SpringDoc 두 가지가 있는데, Springfox Swagger는 2020년 후로 업데이트가 중단되었다. 그래서 SpringDoc을 많이 쓴다고 한다.

Annotation

SpringDoc은 swagger3 annotaion을 사용하고 있다.

@SecurityScheme(name = "petstore_auth", type = SecuritySchemeType.OAUTH2, flows = @OAuthFlows(implicit = @OAuthFlow(authorizationUrl = "https://petstore3.swagger.io/oauth/authorize", scopes = {
		@OAuthScope(name = "write:pets", description = "modify pets in your account"),
		@OAuthScope(name = "read:pets", description = "read your pets") })))
@Tag(name = "pet", description = "the pet API")
public interface PetApi {

	default PetApiDelegate getDelegate() {
		return new PetApiDelegate() {
		};
	}


	@Operation(summary = "Deletes a pet", description = "", security = {
			@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
	@ApiResponses(value = { @ApiResponse(responseCode = "400", description = "Invalid pet value") })
	@DeleteMapping(value = "/pet/{petId}")
	default ResponseEntity<Void> deletePet(
			@Parameter(description = "Pet id to delete", required = true) @PathVariable("petId") Long petId,
			@Parameter(description = "") @RequestHeader(value = "api_key", required = false) String apiKey) {
		return getDelegate().deletePet(petId, apiKey);
	}
    
    	@Operation(summary = "Finds Pets by status", description = "Multiple status values can be provided with comma separated strings", security = {
			@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
	@ApiResponses(value = {
			@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Pet.class)))),
			@ApiResponse(responseCode = "400", description = "Invalid status value") })
	@GetMapping(value = "/pet/findByStatus", produces = { "application/xml", "application/json" })
	default ResponseEntity<List<Pet>> findPetsByStatus(@Parameter(explode = Explode.TRUE, name = "status", in = ParameterIn.QUERY, description = "Status values that need to be considered for filter", style = ParameterStyle.FORM, schema = @Schema(type = "string", defaultValue = "available", allowableValues = { "available", "pending", "sold" })) @Valid @RequestParam(value = "status", required = false) List<String> status) {
		return getDelegate().findPetsByStatus(status);
	}

참고 : https://springdoc.org/
https://oingdaddy.tistory.com/272