[GPT Actions] 7. Chuck Norris Database API
- 공개 API를 기반으로 OpenAPI 스키마 작성에 대한 종합 실습 안내입니다.
- 'Chuck Norris Database' API를 사용하여 무작위 Chuck Norris 농담을 제공하는 API 문서화 예제를 제시합니다.
- 스키마에는 기본 구조 설정, 경로(Paths) 정의, 스키마(Schemas) 정의, 매개변수 추가, 예제 응답 및 외부 문서 정보가 포함됩니다.
공개 API를 기반으로 OpenAPI 스키마를 작성하는 종합 실습을 진행해보겠습니다. 이를 통해 지금까지 배운 내용을 실제로 적용해볼 수 있을 것입니다.
예시로 "Chuck Norris Database" API를 사용하겠습니다. 이 API는 무작위 Chuck Norris 농담을 제공합니다.
Step 1: 기본 구조 설정
먼저 OpenAPI 스키마의 기본 구조를 작성합니다.
openapi: 3.1.0
info:
title: Chuck Norris Jokes API
description: An API to retrieve random Chuck Norris jokes
version: 1.0.0
servers:
- url: http://api.icndb.com/
tags:
- name: jokes
description: Operations related to Chuck Norris jokes
paths:
components:
schemas:
Step 2: 경로(Paths) 정의
API의 주요 엔드포인트를 정의합니다.
paths:
/jokes/random:
get:
summary: Get a random joke
tags:
- jokes
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JokeResponse'
/jokes/{id}:
get:
summary: Get a specific joke by ID
tags:
- jokes
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JokeResponse'
'404':
description: Joke not found
Step 3: 스키마(Schemas) 정의
응답 데이터의 구조를 정의합니다.
components:
schemas:
Joke:
type: object
properties:
id:
type: integer
joke:
type: string
JokeResponse:
type: object
properties:
type:
type: string
value:
$ref: '#/components/schemas/Joke'
Step 4: 매개변수(Parameters) 추가
선택적 매개변수를 추가하여 API의 유연성을 높입니다.
paths:
/jokes/random:
get:
# ... (이전 내용 유지)
parameters:
- name: firstName
in: query
description: Replace Chuck with given first name
schema:
type: string
- name: lastName
in: query
description: Replace Norris with given last name
schema:
type: string
# ... (응답 부분은 그대로 유지)
Step 5: 예제(Examples) 추가
응답의 예제를 추가하여 API 사용자의 이해를 돕습니다.
components:
schemas:
JokeResponse:
# ... (이전 내용 유지)
example:
type: "success"
value:
id: 484
joke: "Chuck Norris can delete the Recycling Bin."
Step 6: 태그(Tags) 및 외부 문서(External Docs) 추가
API에 대한 추가 정보를 제공합니다.
tags:
- name: jokes
description: Operations related to Chuck Norris jokes
externalDocs:
description: API Documentation
url: http://www.icndb.com/api/
최종 OpenAPI 스키마:
openapi: 3.1.0
info:
title: Chuck Norris Jokes API
description: An API to retrieve random Chuck Norris jokes
version: 1.0.0
servers:
- url: http://api.icndb.com/
tags:
- name: jokes
description: Operations related to Chuck Norris jokes
paths:
/jokes/random:
get:
summary: Get a random joke
tags:
- jokes
parameters:
- name: firstName
in: query
description: Replace Chuck with given first name
schema:
type: string
- name: lastName
in: query
description: Replace Norris with given last name
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JokeResponse'
/jokes/{id}:
get:
summary: Get a specific joke by ID
tags:
- jokes
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/JokeResponse'
'404':
description: Joke not found
components:
schemas:
Joke:
type: object
properties:
id:
type: integer
joke:
type: string
JokeResponse:
type: object
properties:
type:
type: string
value:
$ref: '#/components/schemas/Joke'
example:
type: "success"
value:
id: 484
joke: "Chuck Norris can delete the Recycling Bin."
externalDocs:
description: API Documentation
url: http://www.icndb.com/api/
이 예제는 Chuck Norris Jokes API의 기본 기능을 OpenAPI 스키마로 표현한 것입니다. 여기에는 경로 정의, 스키마 정의, 매개변수 설명, 예제 응답 등이 포함되어 있습니다.
실제 API를 문서화할 때는 이 구조를 기반으로 하되, 해당 API의 특성에 맞게 더 많은 엔드포인트, 매개변수, 응답 유형 등을 추가하고 상세한 설명을 포함시킬 수 있습니다.
이 스키마를 Swagger UI나 다른 OpenAPI 호환 도구에 입력하면, 대화형 API 문서를 생성하고 API를 직접 테스트해볼 수 있습니다.