API 설명 언어 cadl 시도

20789 단어 OpenAPIcadltech
코드와 문서를 생성하기 위해 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에서 기술 모드를 기술할 때의 난점이라고 생각한다.
캐럴은 간략한 형식으로 기술하는 것을 첫 번째 목적으로 하는 언어가 아니기 때문에 이를 모델로 특수화할 수 있고 인류가 반년 정도의 공백을 거친 후에도 읽을 수 있는 간결도를 갖추고 있어 보인다.

좋은 웹페이지 즐겨찾기