이벤트 기반 API 설명서가 간단해졌습니다(클라이언트측 렌더링).

📢 원본 기사는 mywebsite에서 볼 수 있으며 인턴십 저널도 찾을 수 있습니다.


이 글은 다른 글과 조금 다릅니다.

이전 게시물에서는 완전 초보자를 위해 작성했지만 이 게시물은 이벤트 기반 프로젝트를 위한 문서 생성을 자동화하고 공식화하려는 개발자를 위한 것입니다.

이 가이드는 AsyncAPI 파일을 사용하여 문서를 생성하는 방법에 대한 지침을 찾는 사람들을 대상으로 합니다. 이벤트 기반 API는 일반적으로 OpenAPI 또는 GraphQL로 문서화하는 동기 API와 동일하지 않습니다. 현재 많은 사람들이 AsyncAPI를 사용하고 있으며 커뮤니티가 클라이언트 측에서 문서를 렌더링하기 위해 어떤 옵션이 있는지 보여주는 가이드를 커뮤니티에 제공할 때입니다.

아, 클라이언트 측 렌더링 또는 서버 측 렌더링에 대해 여전히 확신이 서지 않는다면 여기에서 모든 내용을 읽을 수 있습니다. 👉 Website rendering for beginners (shameless plug 😉).

다음에 대한 사용법을 다룰 것입니다.

React

Vue

Web Components

Standalone Bundle

모든 예제는 이 동일한 AsyncAPI 샘플 파일을 사용합니다 👇

{
  "asyncapi": "2.2.0",
  "info": {
    "title": "Account Service",
    "version": "1.0.0",
    "description": "This service is in charge of processing user signups"
  },
  "channels": {
    "user/signedup": {
      "subscribe": {
        "message": {
          "$ref": "#/components/messages/UserSignedUp"
        }
      }
    }
  },
  "components": {
    "messages": {
      "UserSignedUp": {
        "payload": {
          "type": "object",
          "properties": {
            "displayName": {
              "type": "string",
              "description": "Name of the user"
            },
            "email": {
              "type": "string",
              "format": "email",
              "description": "Email of the user"
            }
          }
        }
      }
    }
  }
}

이것이 생성된 문서의 예상 모습입니다 👇



이 문서의 모든 사용 예는 저장소asyncapi-docs-rendering-examples에서 확인할 수 있습니다.

반응하다

If you wish to render documentation from your AsyncAPI file in React application, then you need to use AsyncAPI React component .

1️⃣ React AsyncAPI 구성 요소를 설치하려면 npm install --save @asyncapi/react-component@next 명령을 실행합니다.

2️⃣ 이제 index.js 파일을 만들고 다음을 입력하십시오.

import React from "react";
import ReactDOM from "react-dom";

import AsyncApiComponent from "@asyncapi/react-component";
import "@asyncapi/react-component/styles/default.min.css";

import { specMock } from "./testDoc";

const rootElement = document.getElementById("root");
ReactDOM.render(<AsyncApiComponent schema={specMock} />, rootElement);

React AsyncAPI 구성 요소는 4행에서 가져옵니다.

AsyncAPI 스타일에 만족하는 경우 import "@asyncapi/react-component/styles/default.min.css";를 사용하여 해당 CSS 패턴을 가져와야 합니다.

7행은 AsyncAPI 샘플 파일을 가져오는 위치입니다.

뷰

If you wish to generate documentation from your AsyncAPI file in Vue application, then you need to use AsyncApiStandalone bundle .

1️⃣ 여기에도 React AsyncAPI 구성 요소가 필요하므로 다시 npm install --save @asyncapi/react-component@next 명령을 실행해야 합니다.

2️⃣ App.vue에 다음 코드를 추가하세요.

<template>
  <div ref="asyncapi"></div>
</template>

<script>
import AsyncApiStandalone from '@asyncapi/react-component/browser/standalone';

// AsyncAPI specification, fetched or pasted.
const schema =
'{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}';

const config = {}; // Configuration for component. This same as for normal React component.

export default {
  name: 'AsyncApiComponent',
  props: {
    msg: String
  },
  mounted() {
    const container = this.$refs.asyncapi;
    AsyncApiStandalone.render({ schema, config }, container);
  }
}
</script>

<style scope src="@/assets/asyncapi.min.css"></style>

6행에서 볼 수 있듯이 import AsyncApiStandalone from '@asyncapi/react-component/browser/standalone'; 명령으로 AsyncApiStandalone 번들을 가져와야 합니다.

3️⃣ 할 일이 하나 더 있습니다. AsyncAPI 스타일링이 마음에 드시면 👉node_modules/@asyncapi/react-component/style/default.min.css로 이동해야 합니다.

해당 파일을 복사한 다음 자산 폴더에 붙여넣습니다.
내 이름을 asyncapi.min.css로 변경했습니다.
import './assets/asyncapi.min.css' 로 main.js 파일에서 가져오거나 내가 했던 것처럼 <style scope src="@/assets/asyncapi.min.css"></style> 로 App.vue 파일 끝에 추가할 수 있습니다.

웹 컴포넌트

To generate documentation from your AsyncAPI file, you can use it as an element of an HTML webpage or as a web component in any other web framework you choose. You can do this by implementing web-react-components .

1️⃣ .html 파일을 만든 다음 이 코드를 복사하여 붙여넣으세요 👇

<script src="https://unpkg.com/@asyncapi/[email protected]/lib/asyncapi-web-component.js" defer></script>

<asyncapi-component
  schema='{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}'

  config='{"show": {"sidebar": false}}'

  cssImportPath="https://unpkg.com/@asyncapi/[email protected]/styles/default.min.css">
</asyncapi-component>

2️⃣ 이전 브라우저에 대한 지원이 필요한 경우 이 스크립트도 추가해야 합니다<script src="https://unpkg.com/@webcomponents/[email protected]/webcomponents-bundle.js"></script> .

그게 다야! 🤯 그냥 굉장해!

독립 실행형 번들

If you want to render documentation from your AsyncAPI file without the use of any framework but with just an HTML webpage then you will need the Standalone bundle .

1️⃣ 기본 HTML 템플릿만 있으면 됩니다.

2️⃣ 헤드 요소에 <link rel="stylesheet" href="https://unpkg.com/@asyncapi/[email protected]/styles/default.min.css">를 입력하여 AsyncAPI 문서 스타일을 가져옵니다.

3️⃣ 본문 요소에 다음을 입력합니다.

 <div id="asyncapi"></div>

    <script src="https://unpkg.com/@asyncapi/[email protected]/browser/standalone/index.js"></script>
    <script>
        AsyncApiStandalone.render({
            schema: '{"asyncapi":"2.4.0","info":{"title":"Account Service","version":"1.0.0","description":"This service is in charge of processing user signups"},"channels":{"user/signedup":{"subscribe":{"message":{"$ref":"#/components/messages/UserSignedUp"}}}},"components":{"messages":{"UserSignedUp":{"payload":{"type":"object","properties":{"displayName":{"type":"string","description":"Name of the user"},"email":{"type":"string","format":"email","description":"Email of the user"}}}}}}}'
            ,
            config: {
                show: {
                    sidebar: false,
                }
            },
        }, document.getElementById('asyncapi'));
    </script>

<script src="https://unpkg.com/@asyncapi/[email protected]/browser/standalone/index.js"></script> 번들에서 필요한 모든 항목을 가져옵니다.

나는 거의 잊었다.

AsyncAPI 구성 요소를 구성하는 방법이 하나 더 있습니다.
일반 React 구성 요소와 동일한 구성 소품을 통해 이를 수행할 수 있습니다.

My Web Component 및 Standalone Bundle 사용 예에는 사이드바를 끄는config='{"show": {"sidebar": false}} 것이 있지만 true로 변경하면 렌더링된 문서에 사이드바가 생깁니다.

이것은 할 수 있는 일의 샘플에 불과했습니다. AsyncAPI는 더 많은 일을 할 수 있습니다. 문서 생성 방법에 대한 자세한 내용은 AsyncAPI documentation을 확인하십시오.

AsyncAPI Client-Side 문서 생성에 대한 이 빠른 가이드가 마음에 드셨기를 바랍니다.

평소와 같이 실수를 발견하면 댓글 섹션에서 화를 내지 마십시오. 저에게 알려주시면 이 문서가 더 나아질 수 있도록 함께 고칠 수 있습니다.