[GPT Actions] 7. Chuck Norris Database API

공개 노트 검색

회원가입 로그인

GPT ACTIONS

[GPT Actions] 7. Chuck Norris Database API

공개 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를 직접 테스트해볼 수 있습니다.