OpenAPI의 필드

OpenAPI(이전의 Swagger)는 API(응용 프로그래밍 인터페이스)를 구축하기 위한 사양입니다. RESTful API를 정의, 문서화 및 사용하는 표준 방법을 제공합니다. OpenAPI 사양은 YAML 또는 JSON 형식으로 작성되며 API의 다양한 측면을 정의하는 데 사용되는 여러 필드를 포함합니다.

OpenAPI에서 가장 일반적으로 사용되는 필드는 다음과 같습니다.

openapi: 사용 중인 OpenAPI 사양의 버전을 지정합니다.
info: 제목, 설명, 버전 및 연락처 정보와 같은 API에 대한 정보를 포함합니다.
servers: API가 호스팅되는 서버를 지정합니다.
paths: API의 끝점(URL)과 여기에 접근할 수 있는 HTTP 메소드(GET, POST, PUT, DELETE 등)를 정의합니다.
components: 스키마, 보안 체계 및 응답과 같은 API의 재사용 가능한 요소를 포함합니다.
security: API가 사용하는 보안 체계를 지정합니다.
tags: 작업 및 끝점을 그룹화하고 구성하기 위한 메타데이터를 제공합니다.
externalDocs: API와 관련된 외부 문서에 대한 링크가 포함되어 있습니다.

이는 OpenAPI 사양에서 사용할 수 있는 필드의 몇 가지 예일 뿐입니다. 필드의 전체 목록은 공식 OpenAPI 사양 문서에서 찾을 수 있습니다.

Apigit은 이러한 필드를 채우는 데 어떻게 기여합니까?

OpenAPI 사양의 모든 필드가 엄격하게 요구되는 것은 아니지만 사양이 유효하고 완전한지 확인하기 위해 포함해야 하는 특정 필드가 있습니다. 다음은 OpenAPI 사양의 필수 필드 중 일부입니다.

openapi: 사용 중인 OpenAPI 사양의 버전을 지정합니다. 이 필드는 필수이며 사양의 루트 수준에 포함되어야 합니다.
info: 제목, 설명, 버전 및 연락처 정보와 같은 API에 대한 정보를 포함합니다. 이 필드는 필수이며 사양의 루트 수준에도 포함되어야 합니다.
paths: API의 끝점(URL)과 여기에 접근할 수 있는 HTTP 메소드(GET, POST, PUT, DELETE 등)를 정의합니다. 이 필드도 필수이며 사양의 루트 수준에 포함되어야 합니다.
servers: API가 호스팅되는 서버를 지정합니다. 이 필드는 반드시 필요한 것은 아니지만 API를 호스팅하는 서버에 대한 정보를 제공하기 위해 포함하는 것이 좋습니다.
components: 스키마, 보안 체계 및 응답과 같은 API의 재사용 가능한 요소를 포함합니다. 이 필드는 반드시 필요한 것은 아니지만 사양의 더 나은 구성 및 재사용성을 위해 포함하는 것이 좋습니다.

유효하고 완전한지 확인하기 위해 OpenAPI 사양에 포함되어야 하는 필수 필드입니다. 다음과 같은 기타 분야security,tags, 그리고externalDocs API의 요구 사항과 사양에 필요한 세부 수준에 따라 포함될 수도 있습니다.

Apigit 대시보드에 API 사양을 추가하려면 왼쪽 상단 모서리에 있는 "+" 기호를 클릭하십시오. "제목" 및 "버전"과 같은 기타 관련 정보와 함께 "test/test.json"과 같은 경로 이름을 입력합니다. 빈 파일은 이러한 모든 필수 필드를 채우는 데 도움이 됩니다.

빈 사양 파일 만들기

그러면 json 코드는 아래와 같습니다.

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

Apigit은 어떻게 더 많은 것을 지원합니까?

Apigit이 양식 형식으로 필드를 채우는 데 어떻게 도움이 되는지 설명하기 위해 다음과 같은 몇 가지 예가 있습니다. 추가하다Field parameter ~에Form

그러면 json 코드는 아래와 같습니다.

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

추가하다Field path ~에Form

그러면 json 코드는 아래와 같습니다.

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },