API 설명 언어 cadl 시도
현재는 캐럿을 기반으로 오픈API를 생성할 수 있고, README는 그래픽QL, gRPC 생성 등도 고려하고 있다.OpenAPI를 생성하는 것보다 직접 사용하는 것이 낫다는 것은 일리가 있다.차이점이 뭘까?
이것은 cadl로 쓴 API 규격으로 OpenAPI로 자주 사용되는 PetStore 모델 정의 와 비슷한 코드를 출력한다.
링크에 있는 json의 패턴 정의에 비해 사람들이 더 쉽게 읽을 수 있는 것은cadl이 아닙니까?
import "@cadl-lang/rest";
import "@cadl-lang/openapi";
import "@cadl-lang/openapi3";
@serviceVersion("1.0.0")
@serviceTitle("Swagger Petstore")
@serviceHost("petstore.swagger.io/v1")
namespace PetStore;
using Cadl.Http;
model Pet {
id: int64;
name: string;
tag?: string;
}
@defaultResponse
@doc("unexpected error")
model Error {
code: int32;
message: string;
}
@route("/pets")
namespace Pets {
@get
@operationId("listPets")
@tag("pets")
op listPets(
@query @doc("How many items to return at one time (max 100)") limit?: int32
): {
@statusCode statusCode: 200;
@header @doc("A link to the next page of responses") "x-next": string;
@body body: Pet[];
} | Error;
@post
@operationId("createPets")
@tag("pets")
op createPets(): CreatedResponse | Error;
@get
@operationId("showPetById")
@tag("pets")
op showPetById(
@path @doc("The id of the pet to retrieve") petId: string
): OkResponse<Pet> | Error;
}
OpenAPI의 정의,cadl에서 생성된 정의(openapp.json)를 바탕으로 과도한 차이를 피하는 방식으로 의미 변경이 없는 diff--- petstore.json 2022-04-06 21:39:43.000000000 +0900
+++ openapi.json 2022-04-06 21:48:03.000000000 +0900
@@ -1,21 +1,22 @@
{
"openapi": "3.0.0",
"info": {
- "version": "1.0.0",
"title": "Swagger Petstore",
- "license": {
- "name": "MIT"
- }
+ "version": "1.0.0"
},
"servers": [
{
- "url": "http://petstore.swagger.io/v1"
+ "url": "https://petstore.swagger.io/v1"
+ }
+ ],
+ "tags": [
+ {
+ "name": "pets"
}
],
"paths": {
"/pets": {
"get": {
- "summary": "List all pets",
"operationId": "listPets",
"tags": [
"pets"
@@ -34,19 +35,24 @@
],
"responses": {
"200": {
- "description": "A paged array of pets",
+ "description": "Ok",
"headers": {
"x-next": {
"description": "A link to the next page of responses",
"schema": {
- "type": "string"
+ "type": "string",
+ "description": "A link to the next page of responses"
}
}
},
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/Pets"
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Pet"
+ },
+ "x-cadl-name": "PetStore.Pet[]"
}
}
}
@@ -64,14 +70,14 @@
}
},
"post": {
- "summary": "Create a pet",
"operationId": "createPets",
"tags": [
"pets"
],
+ "parameters": [],
"responses": {
"201": {
- "description": "Null response"
+ "description": "The request has succeeded and a new resource has been created as a result."
},
"default": {
"description": "unexpected error",
@@ -88,7 +94,6 @@
},
"/pets/{petId}": {
"get": {
- "summary": "Info for a specific pet",
"operationId": "showPetById",
"tags": [
"pets"
@@ -100,13 +105,14 @@
"required": true,
"description": "The id of the pet to retrieve",
"schema": {
- "type": "string"
+ "type": "string",
+ "description": "The id of the pet to retrieve"
}
}
],
"responses": {
"200": {
- "description": "Expected response to a valid request",
+ "description": "The request has succeeded.",
"content": {
"application/json": {
"schema": {
@@ -150,12 +156,6 @@
}
}
},
- "Pets": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Pet"
- }
- },
"Error": {
"type": "object",
"required": [
@@ -170,7 +170,8 @@
"message": {
"type": "string"
}
- }
+ },
+ "description": "unexpected error"
}
}
}
제가 캐럿들에게 기대하는 건 지금까지 Protocol Buffers와 익숙한 도구에 대한 이야기입니다.yugui가 Protobuf의 장점에 대해서 얘기할 때.간단하고 읽기 쉬우며 모든 것을 비교할 수 있지만, 모든 것을 덮어쓰기 위해 팽창하지 않기 때문에 도구를 확장할 수 있습니다.특별히 좋은 것은 아니지만 조금만 써도 이런 소박함이 손쉽게 닿는다.
똑같죠?
그렇다면 프로토버프도 가능하지만 시리아 형식으로 기술된 프로토버프와 패턴 형식으로 기술된 프로토버프를 구분하지 않고 이해하면 라벨의 기술은 흔치 않다나는 라벨에 무엇을 써야 좋을지 모르는 것이 Protobuf에서 기술 모드를 기술할 때의 난점이라고 생각한다.
캐럴은 간략한 형식으로 기술하는 것을 첫 번째 목적으로 하는 언어가 아니기 때문에 이를 모델로 특수화할 수 있고 인류가 반년 정도의 공백을 거친 후에도 읽을 수 있는 간결도를 갖추고 있어 보인다.
Reference
이 문제에 관하여(API 설명 언어 cadl 시도), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://zenn.dev/niku/articles/368006496f37cd텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.
우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)