OpenAPI 결함 - 유형 및 형식

"long"유형의 매개변수/필드를 어떻게 정의하시겠습니까? 쉽죠? 해당 유형으로 매개변수/필드를 선언하기만 하면 됩니다.

자바 및 C#: long the_field
코틀린: the_field: Long
이동: int64 the_field
녹: the_field: i64
모든 프로그래밍 언어에는 매개변수/필드를 코딩하는 "최적화된"방법이 있습니다. 코드 작성은 주로 필드 및 함수 매개변수 정의로 구성되므로 이는 이해할 수 있고 예상됩니다.

체재

이제 OpenAPI 및 JSON Schema에서 어떻게 하시겠습니까? long이 꽤 널리 쓰이니까 쉬울 텐데?
format 필드가 필요합니다.

the_field:
  type: integer
  format: int64

type 및 format 의 두 필드가 필요한 이유는 무엇입니까? type: int64 를 그냥 넣으면 안 되는 이유는 무엇입니까? 유형int64은 OpenAPI 및 JSON 스키마에서 지원하는 유형(문자열, 숫자, 정수, 개체, 배열, 부울, null)에 속하지 않습니다. 다른 모든 유형은 설명을 위해 형식을 사용해야 합니다.

이러한 제한된 유형 시스템은 JSON 자체 이후에 상속된다는 점에 유의할 수 있습니다. OpenAPI 및 JSON 스키마는 JSON에서 충족될 수 있는 유형만 스키마화하도록 설계되었음을 의미합니다. 그러나 이것은 사실이 아닙니다. 유형integer이 JSON 또는 JavaScript에 존재하지 않으므로 사양에서 이미 새 유형을 발명하고 있습니다. int64와 같은 최소한의 모든 기본 유형을 발명하지 않는 이유는 무엇입니까? int64는 혼자가 아니라 다른 유용한 유형이 있습니다.

또한 type 및 format 필드의 동일한 구문이 JSON 스키마와 작업 매개 변수 모두에서 사용됩니다. HTTP 작업 매개변수 정의에는 JavaScript 유형 시스템 제한이 없습니다. 작업 매개변수(쿼리, 헤더, 양식 데이터, 쿠키)는 문자열(또는 문자열 배열)로 직렬화할 수 있어야 합니다. JSON에서 지원하는 유형과는 아무런 관련이 없습니다.

다음은 OpenAPI 문서에 언급된 형식입니다: int32, int64, float, double, byte, binary, date, date-time, uuid.



예, 맞습니다. API 사양은 형식이 지정되지 않은 거의 모든 유형을 사용할 수 없습니다. format 필드가 type 필드보다 더 유용한 것 같습니다.

짧음

마지막으로 OpenAPI 및 JSON 스키마가 내장 유형을 설계한 방식으로 인해 개발자는 더 많은 줄을 작성하거나 추가 구조를 사용해야 합니다.

# There are 3 lines to define the field
the_field1:
  type: integer
  format: int64

# Additional structure
the_field2: { type: integer, format: int64 }

위의 예에는 previous post에서 논의된 필드에 대해 지정된 required 플래그가 없습니다. required 플래그를 format와 함께 지정하면 필드가 더 길어집니다.

다음은 이 디자인에 대한 가능한 수정 사항입니다.

the_field1: int64
the_field2: uuid

이는 일반 프로그래밍 언어에서와 같이 "the_field가 int64 유형을 가짐"을 의미합니다. 위의 유형은 논리적입니다. 직렬화 프로토콜의 일부 유형이 아닙니다. 유형에는 좀 더 많은 의미가 있습니다. 해당 필드에 무엇이 저장됩니까? 어떤 종류의 숫자입니까? 어떤 종류의 문자열입니까? 좋은 사양이 대답해야 하는 모든 질문입니다. 논리적 유형은 여전히 ​​JSON 필드의 기술적 유형을 일관되게 정의합니다: uuid -> string , int64 -> integer , datetime -> string ...

디자인을 활용하여 필드를 필수가 아님(선택 사항)으로 표시할 수 있습니다.

the_field: optional<int64>

대안:

the_field: int64?

위의 코드는 type 도 format 도 required 도 사용하지 않습니다. 우리는 추가 사항을 지정하지 않고 필드 정의의 핵심으로 내려왔습니다. 이는 프로그래밍 언어에서 필드와 매개변수를 포함한 인터페이스를 정의하는 방식과 매우 일치합니다. 짧은 정의를 사용하도록 의도적으로 설계되었습니다. 명세를 더 잘 쓰고 가독성을 높이려면 간결함이 중요합니다.
format 및 type 정의와 같은 특이한 점은 매개변수/필드를 정의하는 더 나은 방법에 익숙한 개발자에게는 매우 생소합니다. 전반적으로 개발자가 사양 작업을 거부한다고 생각합니다. 이 시리즈에서 더 많은 OpenAPI 사양 결함에 대해 읽어보십시오.