Softonic

OpenAPI 필수 필드 검사

단계 1 / 2
다음

API 설명을 동료, 고객 또는 문서 생성기에 넘기기 전에 필수 필드가 모두 있는지 확인하세요. 위에 문서를 붙여 넣으면 도구가 버전 필드, info.title, info.version, paths를 확인하고 누락된 항목을 목록으로 보여 줍니다.

필수 필드를 확인하는 방법

  1. 1

    문서 붙여 넣기

    아직 작업 중이어도 괜찮습니다. 명세를 JSON 또는 YAML로 붙여 넣으세요.

  2. 2

    검사 실행

    결과 단계로 넘어가세요. 누락된 필드마다 개별 오류로 표시됩니다.

  3. 3

    누락된 항목 추가

    아래의 조각 예제를 사용해 표시된 필드를 파일에 추가하세요.

  4. 4

    다시 검사

    수정한 명세를 다시 붙여 넣고, 오류가 더 이상 나오지 않을 때까지 반복하세요.

필수 항목 네 가지

필드 위치 예시
버전 필드 최상위 openapi: 3.0.3 또는 swagger: "2.0"
info.title info 내부 title: Orders API
info.version info 내부 version: 1.0.0
paths 최상위 최소한 첫 번째 경로가 포함된 paths:

info.version 값은 OpenAPI 명세의 버전이 아니라 여러분의 API 버전입니다. 명세 버전이 이미 맨 위에 있어서 이 항목을 빠뜨리는 경우가 많습니다.

모든 항목이 빠진 예제

servers:
  - url: https://api.example.com

이 작은 문서에는 필수 항목이 하나도 없습니다. 보고서에는 오류 세 건이 나옵니다.

발견 사항 유형
Missing ‘openapi’ or ‘swagger’ version field. 오류
Missing ‘info’ object. 오류
Missing ‘paths’ object. 오류

info 객체 전체가 없으면 도구는 그 오류 하나만 보고하고, title과 version을 따로 나열하지 않습니다. info를 두 필드와 함께 추가하면, 다음 실행에서 두 필드 중 아직 빠진 것이 있는지 보고됩니다.

시작용 골격

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

이 골격은 필수 필드 검사를 모두 통과합니다. 이름을 자신의 것으로 바꾸고 거기서부터 확장하세요. 응답, 스키마, 보안은 이 검사의 대상이 아닙니다.

이 검사를 실행해야 하는 때

명세를 처음부터 새로 작성할 때, 코드에서 생성한 후에, 그리고 다른 도구로 가져갈 사람에게 보내기 전에 실행하세요. 많은 가져오기 도구는 첫 번째 필수 필드 누락에서 짧은 메시지를 내고 멈추므로, 한 번에 모두 찾아내면 여러 번 왔다 갔다 하는 수고를 줄일 수 있습니다. 또한 info.version을 자주 잊거나, 초안을 작성하는 동안 paths를 빼먹는 초보자에게도 유용한 확인 단계입니다.

필수 필드 검사를 통과한 뒤 다음으로 유용한 추가 항목은 info 아래의 짧은 description, servers 항목, 각 작업의 operationId입니다. 이 검사에서는 확인하지 않지만, 명세를 읽기 쉽게 만들고 클라이언트 코드로 바꾸기도 쉽게 해 줍니다.

자주 묻는 질문

아니요. openapi 필드는 사용하는 명세의 버전을 나타냅니다. info.version은 여러분 API의 버전이며, 예를 들어 1.0.0과 같습니다.

키는 객체로 존재해야 하지만, 이 검사는 그 안에 경로가 있어야 한다고 요구하지 않습니다. 게시하기 전에 실제 경로를 추가하세요.

title과 version 검사는 info 객체가 있을 때만 실행됩니다. 객체를 추가한 뒤 다시 실행하면 그 필드들이 완전한지 확인할 수 있습니다.

아니요. 여기서 요구하는 것은 버전 필드, info, title, version, paths뿐입니다. 작업 수준의 세부 사항은 검사하지 않습니다.

관련 도구

보색 찾기

어떤 입력에 대해서도 보색을 찾습니다. HSL 반대 색, 분할 보색 쌍, 그리고 접근성 있는 조합 제안을 반환합니다.

Webpack 설정 생성기

순수 JavaScript, React, Vue용 webpack 5 webpack.config.js를 만드세요. TypeScript, Babel, CSS 또는 Sass, 이미지, HtmlWebpackPlugin, 개발 서버, npm install 명령까지 함께 제공합니다.

Protocol Buffers 디코더

hex, Base64, Base64URL, 텍스트 또는 파일의 Protobuf 와이어 형식 바이트를 브라우저에서 디코딩하고 정확한 필드 후보를 확인한 뒤 비공개 보고서로 내보냅니다.

XML 포매터

일관된 들여쓰기로 XML 문서를 정렬 출력하고, 정확한 줄 번호로 적격성 오류를 잡아냅니다.

XSD 검증기

XML 문서를 XSD 스키마에 대해 검증하고, 요소와 타입 불일치를 정확한 줄 번호와 함께 보고합니다.

색상 혼합기

두 HEX 색상을 2-20개의 균등한 색상 견본으로 섞습니다. 양 끝 색상을 포함해 각 중간 색상을 대문자 HEX 코드로 확인하세요.

이 도구는 다른 언어로도 제공됩니다

사용 가이드와 활용 사례