첫 번째 OpenAPI 계약! - OpenAPI [3]

오늘 우리는 간단한 OpenAPI 계약을 함께 살펴보고 각 부분에 대해 자세히 설명합니다.

먼저 오늘 사용할 계약서입니다.

openapi: 3.0.0

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

상단에 API와 관련된 일부 정보가 있고 노출된 유일한 작업의 선언이 있음을 빠르게 확인할 수 있습니다.

오픈 API

이 변수는 이 계약을 작성하는 데 사용되는 사양의 버전을 정의하기 위한 것입니다.
이 글을 쓰는 시점에서 4가지 버전을 사용할 수 있습니다.

3.0.0

3.0.1

3.0.2

3.0.3

이러한 버전은 Semantic Versioning 사양에 따라 정의됩니다. 간단한 이유로 알아두는 것이 중요합니다. 버전이 3.x.x 버전으로 유지될 때까지 계약이 유효하며 해당 버전과 관련된 모든 도구를 계속 사용할 수 있습니다.
그러나 2.x.x 사양 버전으로 계약을 작성하는 경우(또는 사양이 4.x.x로 변경될 때) 브레이킹 체인지로 인해 3.x.x 도구에서 계약이 작동하지 않을 수 있습니다.

현재 모든 OpenAPI 스택은 3.x.x 버전에 적합하므로 괜찮을 것입니다. 그러나이 정보를 명심하십시오.

(시맨틱 버전 관리에 대해 이야기하는 게시물을 확인할 수 있습니다.

더 이상 사용할 수 없는 기사

)

정보

이 부분에는 API에 대한 메타데이터가 포함되어 있습니다. 필수 매개변수는 2개뿐입니다.

제목

버전.

그러나 정보가 많을수록 계약 지원에 가장 좋습니다.

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

매개변수

필드
유형
설명


제목
끈
API 제목

설명
끈
API에 대한 간단한 설명

서비스 약관
끈
API 서비스 약관 URL

연락하다
물체
API를 지원하는 사람/팀에 연락하는 방법을 정의하려면

특허
물체
노출된 API에 대한 라이선스 정보

버전
끈
API 계약의 버전입니다.

서버

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

이 매개변수에는 이 서버의 사용법을 이해하기 위한 약간의 설명과 함께 API를 사용할 수 있는 모든 엔드포인트 목록이 포함됩니다(개발 전용, 프로덕션...).

경로

이 부분은 조금 더 복잡합니다. 무슨 일이 일어나고 있는지 이해하기 위해 주석을 따라 다음 코드를 활짝 열어주세요.

paths: # Contains a list of paths
  /users:  # Example of a path
    get:  # Method which will be allowed for this path. Can be "put", "post", "delete"...
      summary: Returns a list of users. # Summary of the operation exposed for this path and this method.
      description: Optional extended description in CommonMark or HTML. # Longer description of the operation exposed.
      responses: # Responses that can be returned by the API
        '200':    # Status code of the response
          description: A JSON array of user names # Description of the response
          content: # Content of the response
            application/json: # File type of the response
              schema: # Schema to describe how the response is build.
                type: array # This response will be an array of strings.
                items: 
                  type: string
        '404':    # Other status code
          description: Not found # Description of the response without body.

우리는 경로 정의의 작은 부분만 볼 수 있지만 이 부분의 목표는 작업을 노출하는 데 사용할 수 있는 모든 경로/메소드를 정의하는 것입니다.

그런 다음 각 작업에 대해 사용 가능한 모든 매개변수(선택 또는 필수)를 정의할 수 있습니다.

헤더

쿼리 매개변수

본체

또한 귀하가 제공할 수 있는 응답에 대한 모든 정보를 제공하여 발생할 수 있는 일을 소비자에게 알립니다.

따라서 더 자세히 알아보려면 전체 OpenAPI 사양을 확인하십시오. https://swagger.io/specification/


그것이 당신을 도울 수 있기를 바랍니다! 🍺