ApiBlaze: API 요소 검색을 위한 UI

ApiBlaze는 키워드 검색, 객체, 속성 또는 끝점 필터링, 설명 및 코드 예제 보기 등의 API 사양을 탐색하는 도구입니다.ApiBlaze는 API에 대한 번개같이 빠른 특정 질문에 대한 답변을 도와줍니다.너는 이곳에서 시험해 볼 수 있다. apiblaze.admantium.com.
사용자가 API를 선택하면 API 요소 검색 페이지가 표시됩니다.이 페이지에서 API 사양의 다양한 요소인 객체, 속성 및 끝점을 검색하고 볼 수 있습니다.이 블로그 글은 이 페이지를 실현하는 출발점이다.어셈블리를 설명하고 API 객체의 검색, 선택 및 표현을 구현하는 방법에 대해 자세히 설명합니다.속성과 단점은 다음 글에서 설명할 것이다.
본문은 최초로 발표되었다my blog.

API 요소 검색 페이지의 구성 요소

사용자가 탐색하고자 하는 API를 선택하면 페이지ApiElementsSearch가 나타납니다.이 페이지는 다음 구성 요소로 구성됩니다.

객체, 속성 및 끝점에 대한 검색 표시줄

검색 막대를 필터링하는 라디오 그룹

검색 결과의 팝업 섹션 표시

현재 선택한 결과에 대한 설명을 보여주는 부분

현재 선택한 결과

의 코드 표시 부분
이 구성 요소들을 하나하나 작성하기 시작합시다.

검색 표시줄

검색 표시줄은 API spec 검색 표시줄과 유사합니다. 모든 키워드를 수락하고, 백엔드를 호출하여 현재 입력한 값을 검색하고, 검색 결과로 공유 상태를 업데이트합니다.

import { Component } from 'spac'
import SearchApiElementsAction from '../actions/SearchApiElementsAction.js'

export default class ApiElementsSearchBarComponent extends Component {
  render = () => {
    return `
      <input type="text" id="api-elements-search-query" value="${this.getState()
        .apiElementsSearchQuery || 'pod'}" spellcheck="false">
    `
  }

  handleKeyUp (e) {
    switch (e.keyCode) {
      case 40: // Arrow down
        e.preventDefault()
        const searchResultDom = document.querySelector('div.search-result')
        searchResultDom && searchResultDom.focus({ preventScroll: false })
        break
      default:
        this.updateState({ apiElementsSearchQuery: e.target.value })
        break
    }
  }

  triggerSearch (keyword) {
    new SearchApiElementsAction().run(keyword, json =>
      this.updateState({ apiElementsSearchResult: json })
    )
  }
}

결과 팝업 창

결과 팝업 창은 또한 API 사양을 검색하는 팝업 창과 유사합니다. 이 창은 공유 상태에서 나타나는 모든 검색 결과의 목록을 표시합니다.또한 화살표 키를 사용하여 탐색하는 UI 상호 작용도 동일합니다.
대표성은 다르지.API를 검색하면 백엔드에서 다음과 같은 데이터 구조를 사용할 수 있습니다.

[
  {
    name: 'Pod',
    containingObject: 'io.k8s.api.core.v1.Pod',
    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.',
    score: 5
  }
  //...
]

이 구조는 다음과 같은 방법으로 구현됩니다.

_renderSearchResults() {
  Object.entries(apiElementsSearchResult).forEach((value, key) => {
    const [i, object] = value
    const { name, containingObject, description } = object

    var html = `
      <div class="search-result" tabindex="${key}" ref="${name}">
        <div class="parent-object">
          ${containingObject}
        </div>
        <div class="title">
          <i>${icons.endpoint}</i>
          ${name}
        </div>
        <div class="description">${description}</div>`
    html = html.concat(`</div>`)
    this.addDom('#api-search-results', html)
  })
}

전체적으로 다음과 같은 레이아웃이 표시됩니다.

API 요소 설명

검색 결과 목록에서 어떤 항목을 선택하든지 (이 항목을 클릭하거나 선택할 때 enter 키를 누르면) 설명과 코드 예시에 표시됩니다.
설명은 현재 선택한 항목에서 값을 가져오고 HTML 표현을 보여 주는 간단한 구성 요소입니다.

_renderObject(details) {
  const { name, containingObject, description } = details

  return `
    <h2>${name}</h2>
    <div class="title">
    <i>${icons['object']}</i>
    <strong>${containingObject}</strong>
    </div>
    <div class="description">${this.format(description)}</div>
  `
}

코드 예제 렌더링

마지막 구성 요소는 전면적인 코드 예시를 보여 줍니다.객체의 내부 데이터는 다음과 같습니다.

{
  name: "Pod",
  // ...
  properties: {
    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"
    }
  }
}

이 구조를 바탕으로 예시 코드 표시를 만들었습니다.이 실현은 대략 100줄의 코드가 있다. 너무 단조롭고 이해할 수 없기 때문에 나는 일반적인 절차만 개술할 뿐이다.

JSON 데이터 구조를 양호한 형식의 문자열로 변환

문자열 정리, 예를 들어 추가 공백 삭제, 인용부호 변환

각 키 값 쌍을 코드 행으로 렌더링하고 행 번호

를 추가합니다.

서식 적용 값 쌍(예: 체크 표시를 <code>로 렌더링

이렇게 하면 다음 레이아웃이 발생합니다.

검토: ApiBlaze 프로젝트 요구 사항

검색 표시줄, 팝업 창, 설명, 코드 예시가 있는 API 요소 검색 페이지를 설계하고 실현함으로써, 우리는 모든 수요를 만족시키는 방향으로 나아가고 있습니다.현재 상황을 살펴보겠습니다.
API 요소 표시

✅ DIS01 - 객체 설명 표시

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

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

.

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

보시다시피 완성해야 할 두 가지 요구가 있습니다.속성은 코드 예시가 아니라 대상 목록을 참조합니다.단점의 표현 방식은 완전히 다르다. HTTP 방법에 따라 설명, 요청 데이터 모델과 응답 데이터 모델이 표시된다.

결론

이 문서에서는 API 요소 검색 페이지를 어떻게 구현하는지 설명합니다.나는 페이지를 어떻게 다른 구성 요소로 구성하는지 설명했다. 왼쪽의 검색 표시줄, 검색 수정기, 결과 팝업 창, 왼쪽의 선택한 요소 설명과 코드 표시.에서는 구성 요소 구현의 세부 사항과 내부 API 사양을 HTML로 변환하는 절차에 대해 설명합니다.다음 기사에서는 API 요소 검색 페이지를 속성과 끝점 표현으로 확장합니다.