ApiBlaze: 속성 및 끝점을 위한 검색 API 설계

ApiBlaze는 키워드 검색, 객체, 속성 또는 끝점 필터링, 설명 및 코드 예제 보기 등의 API 사양을 탐색하는 도구입니다.ApiBlaze는 API에 대한 번개같이 빠른 특정 질문에 대한 답변을 도와줍니다.너는 이곳에서 시험해 볼 수 있다. apiblaze.admantium.com.
API 요소를 검색하면 객체, 속성 및 끝점이 표시됩니다.그것들을 선택하면, 대상은 데이터 모델, 속성, 그리고 정렬된 대상 목록을 표시하고, 단점은 요청 매개 변수와 복잡한 응답 대상을 표시합니다.
본고에서 우리는 속성과 단점을 표시하는 데 필요한 수정을 소개하고 ApiBlaze의 개발 과정을 완성할 것이다.
본문은 최초로 발표되었다my blog.

세부 정보 로드 요청 처리

사용자가 검색 결과를 클릭하면 프런트엔드에서 세부 정보를 로드하도록 요청합니다.백엔드에서 요청한 대상 유형을 구분하고 특정한 처리 방법을 호출합니다.

function apiElementsDetailsSearchAction (object) {
  switch (object.type) {
    case 'object':
      return loadObject(object)
    case 'property': 
      return loadProperty(object)
    case 'endpoint':
      return loadEndpoint(object)
}

속성을 불러오는 방법을 계속 알아보겠습니다.

속성 검색 및 렌더링

속성에 대해서는 이름, 설명, 유형, 그리고 이 속성을 사용하는 모든 대상의 목록이 필요합니다.다음 절차에 따라 이 정보를 수집합니다.

로드 속성

의 포함 대상

포함 대상

에 속성을 불러오는 정의

속성이 있는 경우 모든 객체를 검색하고 이름을 저장합니다

.
이로 인해 생성되는 데이터 구조는 다음과 같습니다.

{
  "name": "imagePullSecrets",
  "containingObject": "io.k8s.api.core.v1.ServiceAccount",
  "type": "Property",
  "attrType": "array",
  "description": "ImagePullSecrets is a list of references to secrets in the same namespace to use for pulling any images in pods that reference this ServiceAccount. ImagePullSecrets are distinct from Secrets because Secrets can be mounted in the pod, but ImagePullSecrets are only accessed by the kubelet. More info: https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod",
  "containingObjectList": [
    "io.k8s.api.core.v1.ServiceAccount",
    "io.k8s.api.core.v1.PodSpec"
  ]
}

프런트엔드에서 이 구조를 사용하고 다음 표현을 생성합니다.

끝점 검색 및 렌더링

끝점은 특수 처리가 필요한 유일한 실체다.API 사양을 로드하면 끝점이 인덱스되고 HTTP 방법을 따라 분리됩니다.예를 들어, GET 및 POST 메서드가 모두 적용될 경우 두 항목이 생성됩니다.다음 예는 다음과 같습니다.

{
  name: "POST /api/v1/namespaces/{namespace}/pods",
  containingObject: "/api/v1/namespaces/{namespace}/pods",
  type: "Endpoint",
  description: "create a Pod",
  score: 3
},
{
  name: "GET /api/v1/namespaces/{namespace}/pods",
  containingObject: "/api/v1/namespaces/{namespace}/pods",
  type: "Endpoint",
  description: "list or watch objects of kind Pod",
  score: 3
}

두 검색 항목은 같은 단점 규범을 인용한다.우리는 이 규범에서 관련 정보를 추출해야 한다.
이러한 절차는 매우 복잡하므로 처음부터 시작하겠습니다. 최초의 OpenAPI 사양post 끝점은 다음과 같습니다.

"/api/v1/namespaces/{namespace}/pods": {
  "post": {
    "consumes": [
      "*/*"
    ],
    "description": "create a Pod",
    "operationId": "createCoreV1NamespacedPod",
    "parameters": [
      {
        "in": "body",
        "name": "body",
        "required": true,
        "schema": { 
          // ... 
        }
      },
      {
        "description": "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed",
        "in": "query",
        "name": "dryRun",
        "type": "string",
        "uniqueItems": true
      },
      // ....
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/io.k8s.api.core.v1.Pod"
        }
      },
      // ...
    },
  }
}

단점에는 두 가지 재미있는 정보가 있다. parameters와 responses.

처리 끝 매개변수

매개변수는 질의 매개변수로 전달되고 URL에 추가될 수 있습니다.또는 JSON으로 요청 체내에 부하하여 전달할 수 있다.검색 매개 변수는 간단한 키 값이 맞지만 주체 매개 변수는 이전 글에서 소개한 끼워 넣은 복잡한 대상이다.
다음 절차에 따라 매개변수를 조작합니다.

속성in === 'query'이 있는 모든 매개변수 필터링

이 프로젝트의 경우 스토리지 속성description 및 type만

속성in === 'body'이 있는 항목이 있으면 모든 매개변수를 필터링합니다.

이 항목에 대해 끼워 넣은 schema 속성 처리

이러한 변환을 위와 같은post 끝점에 적용하면 다음과 같은 데이터 구조가 생성됩니다.

"queryParameters": [
  "dryRun": {
    "_description": "When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed",
    "_type": "string",
  },
  "fieldManager": {
    "_description": "fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.",
    "_type": "string",
  }
  ]
},
"bodyParameters": {
  "apiVersion": {
    "_type": "string",
    "_description": "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources"
  },
  "kind": {
    "_type": "string",
    "_description": "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds"
  },
}

주체 파라미터와 조회 파라미터는 각자의 코드 상자에 나타난다.이전과 마찬가지로 JSON 구조는 문자열로 변환되고 여러 HTML 변환이 적용됩니다.

renderEndpoint() {
  const { bodyParameters, queryParameters } = this.getState().searchApiElementDetails

  document.querySelector(this.querySelector).innerHTML = 
    this.style(this.format(bodyParameters), "Body Parameters") +
    this.style(this.format(queryParameters), "Query Parameters") +
}

다음 예는 다음과 같습니다.

처리 끝점 응답

최초의 OpenAPI 사양에서 응답은 HTTP 상태 코드를 adescription와 aschema가 있는 객체에 매핑합니다.다음은 상태 코드200의 예입니다.

"/api/v1/namespaces/{namespace}/pods": {
  "post": {
    // ...
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/io.k8s.api.core.v1.Pod"
        }
      },
      // ...
    },
  }
}

옵션 요소schema는 중첩된 객체를 가리킵니다.이로 인해 생성되는 데이터 구조는 다음과 같습니다.

"responses": {
  "200": {
    "_description": "OK",
    "properties": {
      "_type": "object",
      "_description": "Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts.",
      "apiVersion": {
        "_type": "string",
        "_description": "APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources"
      },
      "kind": {
        "_type": "string",
        "_description": "Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds"
      }
      //...
    }
  },
  "201": {
    "_description": "Created",
    "properties": {
      "_type": "object",
      "_description": "Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts."
    }
  },
  //...
}

렌더링할 때 각 상태 코드는 코드 상자에 중첩된 객체가 표시되는 별도의 섹션입니다.

ApiBlaze 프로젝트 요구 사항 완료

이러한 변경을 완료하면 ApiBlaze의 모든 요구 사항을 충족할 수 있습니다.

검색 API

✅ SEA01 - 키워드별 API 검색

✅ SEA02 - 팝업 창에 검색 결과 표시

✅ SEA03 - 화살표 키를 사용하여 검색 결과를 선택하고 마우스

를 입력하고 클릭합니다.

API 요소 검색

✅ SEL01 - 객체, 특성 및 끝점 구분

✅ SEL02 - 키워드별 API 요소 검색

✅ SEL03 - 팝업 창에 검색 결과 표시

✅ SEL04 - 화살표 키를 사용하여 검색 결과를 선택하고 마우스

를 입력하고 클릭합니다.

API 요소 표시

✅ DIS01 - 객체 설명 표시

✅ DIS02 - 객체를 선택할 때: 객체의 전체 데이터 모델 표시

✅ DIS03 - 속성을 선택할 때: 속성을 사용하는 객체를 표시합니다

.

✅ DIS04 - 끝점을 선택할 때: 요청 및 응답 객체 표시

프레임

✅ FRAME01 - 컨트롤러 및 케이블 연결

✅ FRAME02 – 상태 페이지 및 구성 요소 있음

✅ 프레임 03-액션

✅ FRAME04 – 최적화 번들

기술

✅ TECH01 - PlainJS 및 사용자 정의 프레임 사용

✅ TECH02 - CSS에서 SAAS 사용

✅ TECH03 - WebSocket을 사용하여 프런트엔드 및 백엔드 연결

결론

ApiBlaze의 발전 과정은 길고 지식이 밀집되어 있다.최초의 원형은 2020년 중반, 나는 긴 휴식을 취한 후 이 프로젝트를 재개했다.수요의 끊임없는 변화: 핵심 기능 외에 웹소켓과 사용자 정의 프레임워크를 사용하여 나의 지식을 깊이 있게 하고 싶다.이상하게도 하나의 틀을 개발하는 것 자체가 하나의 여정이 되어 자바스크립트 지식을 깊이 있게 하는 데 매우 유익한 여정이다.다른 JavaScript 프레임워크를 읽고 그 프레임워크가 어떻게 작동하는지 이해할 때, 나는 그것들의 기능과 응용 프로그램 설계를 어떻게 도와주는지 더 잘 이해할 수 있다.마지막으로 저는 이 여정을 마쳐서 매우 기쁩니다. ApiBlaze를 사용하여 API 규범을 신속하게 검색하시기 바랍니다.