OpenAPI Spec 문서 간단한 작성 방법

paths: /users/{userId}/cards: get: tags: - users summary: 이용자가 발급한 카드 목록 조회 description : 이용자 계정에 해당하는 발급된 카드 목록을 가져옵니다. parameters: - name: userId in: path # path parameter에 대한 정의 description: 조회하고자 하는 유저의 아이디값을 입력합니다. required: true schema: type: integer format: int32 minimum: 1 - name: status in: query # query parameter에 대한 정의 style: form description: 조회하고자 하는 카드의 상태를 입력합니다. schema: type: boolean example: true enum: - true - false responses: '200': description: Pagination 된 유저 정보 응답값 content: application/json: schema: # Response 값 형태를 정의한 component입니다. # 이에 대한 설명은 아래에서 설명하도록 하겠습니다. $ref: "#components/schemas/UserCards"

paths: /users: post: tags: - users summary: 이용자 계정 생성 description : 이용자 계정을 생성합니다. 계정 생성 시 비밀번호 입력 확인의 경우 프론트에서 검증합니다. requestBody: $ref: "#components/requestBodies/User" responses: '200': description: 생성된 유저의 최소 데이터를 반환합니다. content: application/json: schema: $ref: "#components/schemas/User" '400': description: 값을 잘못 입력할 경우 에러를 반환합니다. content: application/json: schema: $ref: "#components/schemas/Error" type: object '409': description: 이미 유저 계정이 동일한 게 존재할 경우 에러를 반환합니다. content: application/json: schema: $ref: "#components/schemas/Error" type: object

components: requestBodies: User: content: application/json: schema: type: object required: - email - password - birthDate - gender - phoneNumber properties: email: type: string example: kkamikoon@gmail.com description: 아이디로 사용할 Email을 입력합니다. password: type: string example: testtest description: 비밀번호를 입력합니다. birthDate: type: string example: 19940101 description: 태어난 생년월일을 기입하며 형태는 `YYYYMMDD` 입니다. gender: type: string example: 'female' description: 성별을 나타내는 문자열이 들어갑니다. (male/female) phoneNumber: type: string example: "01012341234"

components: schema: CardDetail: allOf: - $ref: "#components/schemas/Card" - type: object properties: alias: type: string description: 카드 별명 example: "황금별의 황금카드" cardKey: type: string format: uuid description: 카드를 특정할 수 있는 고유 아이디 값 example: ef4de7b28f214fcfac8ee5d1c8261b20 cardName: type: string description: 카드 이름 example: "KB국민카드" Card: type: object properties: id: type: integer description: 카드의 고유 아이디 값 status: type: boolean enum: - true - false description: 카드 상태 (0 비활성, 1 활성 ) cardNumber: type: string description: 마스킹 된 카드 번호 example: "1234-****-****-*210" createdAt: type: string format: date-time description: 카드 정보가 생성된 날짜 updatedAt: type: string format: date-time description: 카드 정보가 업데이트된 날짜 UserWithCard: $ref: "#components/schemas/User" type: object properties: card: $ref: "#components/schemas/CardDetail" description: 현재 활성화 돼 있는 카드 정보를 반환합니다. 만약 카드가 없을 경우 null 값이 반환됩니다. type: object User: type: object required: - id - nickname - phoneNumber - gender - birthDate - email - isActive - createdAt - updatedAt - lastAccessed properties: id: type: integer format: int64 example: 1 description: 유저의 고유 아이디 nickname: type: string description: 유저의 닉네임 example: 황금별 phoneNumber: type: string description: 휴대폰 번호 example: "01012341234" gender: type: string description: 유저의 성별 enum: - 'male' - 'female' birthDate: type: string example: 19940101 description: 태어난 생년월일을 기입하며 형태는 `YYYYMMDD` email: type: string description: 유저의 이메일 example: kkamikoon@gmail.com createdAt: type: string format: date-time description: 유저 계정이 생성된 날짜 updatedAt: type: string format: date-time description: 유저 계정이 업데이트된 날짜 lastAccessed: type: string format: date-time description: 마지막 접속 날짜 Error: type: object required: - code - message properties: code: type: string description: 에러 코드 example: "ERROR-FOUND" message: type: string description: 에러에 대한 상세 메시지 example: "에러메시지 입니다."