springdoc-openapi๋ฅผ ์ฌ์ฉํ์ฌ ๋ด ์ ํ๋ฆฌ์ผ์ด์ ์ ์ปจํธ๋กค๋ฌ ๋ฐ ๋ชจ๋ธ์ Swagger 3 ์ฃผ์์ ๊ธฐ๋ฐ์ผ๋ก OAS3 yaml ์ฌ์์ ์์ฑํฉ๋๋ค.
๋ด๊ฐ ๋ฌ์ฑํ๊ณ ์ถ์ ๊ฒ์ ์ธ๋ผ์ธ ์์ ์๋ต์ ๊ฐ๋ ๊ฒ์ ๋๋ค. ์ด ๊ฐ์:
paths:
/myoperation:
get:
...
responses:
'200':
content:
application/json:
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
results:
type: array
...
์ปจํธ๋กค๋ฌ ํด๋์ค์ ์์ ๋ฉ์๋ ์ฃผ์์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
@ApiResponse(responseCode = "200",
description = "OK",
content = @Content(mediaType = "application/json", schema = @Schema(implementation = MyResponseDTO.class, requiredProperties = { "count", "results"} ))
๋ฐ MyResponseDTO:
public class MyResponseDTO {
@Schema(required = true, description = "")
private long count;
@ArraySchema(schema = @Schema(implementation = MyModel.class))
private List<DTO> results;
... getters/setters
}
๊ทธ ๊ฒฐ๊ณผ ๋ค์๊ณผ ๊ฐ์ ์คํค๋ง๊ฐ ์์ฑ๋ฉ๋๋ค.
...
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/MyResponseDTO'
...
components:
MyResponseDTO:
required:
- count
type: object
properties:
count:
type: integer
format: int64
results:
type: array
items:
$ref: '#/components/schemas/MyModel'
์๋ต ๋ด์ฉ์ ์ธ๋ผ์ธ ๊ฐ์ฒด๊ฐ ์๋ ์ฐธ์กฐ์ ๋๋ค. ๋ฌธ์์ ์ธ๋ผ์ธ์ผ๋ก ํ์๋๋๋ก ์๋ต/์คํค๋ง์ ์ฃผ์์ ๋ฌ ์ ์๋ ๋ฐฉ๋ฒ์ด ์์ต๋๊น?
๋๋ ์ด๋ฏธ ์ด ์ง๋ฌธ์ springdoc-openapi์ ๋ํ ๋ฌธ์ ๋ก ๊ฒ์ํ์ต๋๋ค. ๊ทธ๋ฌ๋ ๊ทธ๋ค์ ๋์๊ฒ ์ฌ๊ธฐ์ ์ง๋ฌธ์ ํ๋ผ๊ณ ์กฐ์ธํ์ต๋๋ค.
์ฌ๊ธฐ ๋๊ตฐ๊ฐ๊ฐ ๋๋ฅผ ๋์ธ ์ ์์ต๋๊น? ๊ฐ์ฌ ํด์!
๋ผ๋ชฌ ๋ก์ค
๋๋ ์ฐ๋ฆฌ๊ฐ ๊ทธ๋ ๊ฒ ํ ๋ฐฉ๋ฒ์ด ์๋ค๊ณ ์๊ฐํฉ๋๋ค(๊ทธ๋ฌ๋ @frantuma ๊ฐ ๋๋ฅผ
์ธ๋ผ์ธ ์ ์๋ฅผ ์ฐพ๋ ์ด์ ๋ ๋ฌด์์ ๋๊น? ์ผ๋ฐ์ ์ผ๋ก ์ฐธ์กฐ๋ ์ ์๋ ๊ด๋ฆฌํ๊ธฐ ์ฝ์ง๋ง ์ฌ์ฉ ์ฌ๋ก๋ฅผ ์ดํดํ๊ณ ์ถ์ต๋๋ค.
ํ์ฌ์์ ์ฐ๋ฆฌ ์ ํ์ด ๊ตฌํํด์ผ ํ๋ OAS3 ์ธํฐํ์ด์ค๋ฅผ ์ง์ ํ์ต๋๋ค. ์ธํฐํ์ด์ค ๋ฌธ์(yaml)์๋ ์ธ๋ผ์ธ ์์
์๋ต์ด ํฌํจ๋์ด ์์ต๋๋ค.
์๊ตฌ ์ฌํญ ์ค ํ๋๋ ๋์ผํ ๋ฌธ์๋ฅผ ์ ๊ณตํ๋ ๊ฒ์
๋๋ค. ์ฆ, ์ 3์๊ฐ ์ ๊ณตํ ๊ฒ๊ณผ ๋๊ฐ์ ๋ฌธ์๋ฅผ ์์ฑํ๊ธฐ ์ํด Spring ์ปจํธ๋กค๋ฌ/๋ชจ๋ธ์ ์ฃผ์์ ๋ฌ๋ ค๊ณ ํฉ๋๋ค.
๋ฐ๋ผ์ ์ธ๋ผ์ธ ์๋ต์ ์ฌ์ฉํ๋ ๊ฒ์ ๊ฐ์ธ์ ์ธ ์ ํ์ด ์๋๋ผ ๊ท์ ๋ ๊ฒ์
๋๋ค.
์์์ด์. ๊ทธ๋์ ์ง๊ธ ๋น์ฅ์ ์ด๊ฒ์ ํ๋ ๊ฐ๋จํ ๋ฐฉ๋ฒ์ด ์์ต๋๋ค. @Schema
์ฃผ์ ๋ด๋ถ์ ์คํค๋ง๋ฅผ ์๋์ผ๋ก _์_ํ ์ ์์ง๋ง, ๊ทธ๊ฒ์ด ํฌ๊ณ ๋ณต์กํ ํด๋์ค๋ผ๋ฉด ๊ณ ํต์ค๋ฌ์ธ ๊ฒ์
๋๋ค.
๋ ์๋ํํ๋ ค๋ฉด ์ธ๋ผ์ธ์ด์ด์ผ ํ๋ค๋ ๋ ๋ค๋ฅธ ์ฃผ์์ ๋ง๋ค๊ณ Reader๋ฅผ ํ์ฅํ์ฌ ๊ทธ๋ฐ ๋ฐฉ์์ผ๋ก ์ฒ๋ฆฌํ ์ ์์ต๋๋ค.
์๊ฒ ์ต๋๋ค. ์ ์ํด ์ฃผ์
์ ๊ฐ์ฌํฉ๋๋ค. ์๋ ์ค๋ช
์ ์๋ํ๊ฒ ์ต๋๋ค.
์๋ง๋ ๋ฏธ๋์๋ @Schema
์ฃผ์์ ๋ํ ์ถ๊ฐ inline=true|false
์์๊ฐ ์ข์ ๊ฒ์
๋๋ค.
๊ฐ์ฅ ์ ์ฉํ ๋๊ธ
์๊ฒ ์ต๋๋ค. ์ ์ํด ์ฃผ์ ์ ๊ฐ์ฌํฉ๋๋ค. ์๋ ์ค๋ช ์ ์๋ํ๊ฒ ์ต๋๋ค.
์๋ง๋ ๋ฏธ๋์๋
@Schema
์ฃผ์์ ๋ํ ์ถ๊ฐinline=true|false
์์๊ฐ ์ข์ ๊ฒ์ ๋๋ค.