Rapi Doc 및 Vitepress를 사용하여 우아한 OpenAPI 사양 문서 만들기

최근에 OpenAPI 사양 문서를 지원하는 문서 페이지를 만들어야 했습니다. OpenAPI 사양 문서란 무엇입니까? 자체 호스팅되거나 API 관리 플랫폼에 포함된 페이지로, 사용자가 OpenAPI JSON 또는 YAML을 기반으로 사용 가능한 엔드포인트, 메소드, 웹후크 등을 확인할 수 있습니다.

최대한 많은 사용자 정의 옵션이 필요한 것과 빠른 설정 및 배포를 위해 즉시 사용 가능한 도구를 사용하는 것 사이에서 균형을 찾아야 했습니다.

그리고 어디든 삽입할 수 있는 웹 컴포넌트인 Rapi Doc을 발견했습니다.

구성요소가 준비되었으므로 맞춤 구성요소를 지원하는 문서를 작성하기 위한 도구가 필요했습니다.

그래서 저는 Vitepress를 선택했습니다. 그리고 병합하고 싶은 두 가지 도구가 있었습니다. 어떻게 됐나요? 알아봅시다.

개발자 모드에서 앱 실행

Vitepress 설정에 대한 이야기는 생략하겠습니다. 기본 페이지에서 지침을 찾을 수 있습니다.

rapi-doc 웹 구성 요소를 포함하는 사용자 정의 RapiDoc.vue 구성 요소도 만들었습니다.

<script setup>
import 'rapidoc'
</script>

<template>
<div>
  <rapi-doc spec-url="https://petstore.swagger.io/v2/swagger.json" render-style="read" style="height:100vh; width:100%"> </rapi-doc>
</div>
</template>

<style scoped>

</style>

이 사용자 정의 구성 요소를 api-docs.md 페이지에도 포함했습니다. (예, Markdown에 Vue 구성 요소를 포함할 수 있습니다. 저는 Vitepress를 좋아합니다!) 내 Vitepress 문서에서 볼 수 있었습니다. .

---
sidebar: false
layout: page
---

<script setup>
import RapiDoc from './components/RapiDoc.vue';
</script>

<rapidoc></rapidoc>

모든 것이 순조롭게 진행되기를 기대하면서 Yarn docs:dev를 실행했습니다. (두 문서의 지침을 모두 따랐으니 괜찮겠죠?)...

그리고 저는 이것을 얻었습니다:

그리고 브라우저가 멈췄습니다.

우후, 무한 루프 만세!

무슨 일이 일어났나요? 그럼 rapi-doc는 웹 컴포넌트이기 때문에 Vue 컴파일러에게 이를 파싱하지 말라고 명시적으로 알려줘야 합니다. 그냥 놔두는 것.

그리고 config.mts 파일 내에 다음을 추가해야 했습니다.

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  ...
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag: string) => {
          return tag.indexOf('rapi-doc') >= 0;
        }
      }
    }
  },
})

맞춤 요소를 확인하고 Vue에 "이 태그는 금지되어 있습니다"라고 알리기만 하면 됩니다.

그래서 우리는 그것을 가지고 있고 실행됩니다!

그런 다음 배포를 설정할 수 있도록 빌드해 보았습니다.

앱 빌드

yarn docs:build 명령을 실행했습니다. 그리고 즉시(와, Vite, 빠르군요!) 다음 오류가 발생했습니다.

이 오류는 빌드 시간 동안 Vite가 자체 속성에 액세스할 수 없음을 의미합니다. 이는 서버(예: Nuxt 또는 기타 SSR 프레임워크)에서 브라우저 API(예: 창)에 액세스하려고 시도하는 경우에도 발생할 수 있습니다.

그럼 우리가 할 수 있는 일은 무엇일까요? 런타임에 동적으로 가져올 수 있습니다!

다음에서 가져오기를 변경해 보겠습니다.

<script setup>
import 'rapidoc'
</script>

<template>
<div>
  <rapi-doc spec-url="https://petstore.swagger.io/v2/swagger.json" render-style="read" style="height:100vh; width:100%"> </rapi-doc>
</div>
</template>

<style scoped>

</style>

이것에:

---
sidebar: false
layout: page
---

<script setup>
import RapiDoc from './components/RapiDoc.vue';
</script>

<rapidoc></rapidoc>

이제 빌드가 문제 없이 통과될 것입니다! API 사양 문서를 즐겨보세요!

보너스: 다크 모드

Vitepress에는 기본적으로 작동하는 다크 모드가 포함되어 있습니다. 하지만 RapiDoc 문서가 모드 변경에 반응하도록 하려면 어떻게 해야 할까요?

Vitepress 핵심 컴포저블인 useData를 사용할 수 있습니다. 여기에는 다크모드 활성화 여부에 대한 정보가 포함된 isDark 속성이 포함되어 있습니다.

SFC의 스크립트 섹션 내에서 사용해 보겠습니다.

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  ...
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag: string) => {
          return tag.indexOf('rapi-doc') >= 0;
        }
      }
    }
  },
})

이제 테마 참조가 있으면 속성 바인딩을 통해 이를 rapi-doc 웹 구성 요소에 전달할 수 있습니다.

<script setup>
import 'rapidoc';
</script>

다크 모드가 제대로 작동하려면 테마 변경에 대응하는 기능을 한 가지 더 추가해야 합니다.

스크립트 섹션에 감시자를 추가해 보겠습니다.

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  import('rapidoc');
});
</script>

그리고 짜잔, 테마 변경에 반응하는 API 문서를 만드셨습니다!

위 내용은 Rapi Doc 및 Vitepress를 사용하여 우아한 OpenAPI 사양 문서 만들기의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!