[GPT Actions] 7. Chuck Norris Database API

달의이성2024-07-19 22:22

요약

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