Komponenty dokumentacji

Osadź dokumentację API na swojej istniejącej stronie

Dodaj interaktywną dokumentację API do strony, którą już masz. Użyj jednego custom elementu dla całej dokumentacji albo złóż stronę z pojedynczych operacji i schematów.

Osadź dokumentację API Wypróbuj przykłady na żywo

Twój framework zostajeStandardowe custom elements działają w zwykłym HTML-u, CMS-ie, React, Vue, Svelte lub Angularze. Żadnych bindingów do frameworka do instalowania.
Czytelne, zanim uruchomi się JavaScriptPrerenderowana z deklaratywnym shadow DOM, dokumentacja jest dostępna dla czytelników i wyszukiwarek, zanim uruchomi się JavaScript.
Ostylowane jak reszta Twojej stronyWłasności CSS i ::part() stylują komponenty. Jasna i ciemna paleta mogą podążać za ustawieniem systemu.

Twoja strona z dokumentacją w środku

Elementy stoją między Twoimi własnymi akapitami, w Twoim układzie i Twojej nawigacji. Jeden element renderuje całą dokumentację; części składają Twoją własną stronę.

Szare linie to Twój tekst; niebieskie ramki to elementy, które czytają jeden dokument i dzielą jego serwer i dane uwierzytelniające.

Kompletna dokumentacja w jednym tagu

Po zaimportowaniu komponentów dodaj <apg-api-reference> do swojej strony. Renderuje wyszukiwanie, nawigację, uwierzytelnianie, operacje, schematy i Try it out. Tu czyta dokument OpenAPI.

<apg-api-reference spec-url="/openapi.yaml"></apg-api-reference>

Dokumentacja OpenAPI wyrenderowana przez apg-api-reference: nawigacja z wyszukiwaniem, serwery i uwierzytelnianie.

Otwórz zrzut ekranu w pełnym rozmiarze

Albo Twoja własna strona, z części

Umieść operację lub schemat obok własnych wyjaśnień. Komponenty tego samego dokumentu dzielą wybrany serwer i dane uwierzytelniające, włącznie z formularzem Try it out.

<apg-spec spec-url="/openapi.yaml">
  <apg-overview></apg-overview>
  <h2>Quick start</h2>
  <apg-auth schemes="ApiKey"></apg-auth>
  <apg-operation operation-id="getPet" try-it="none"></apg-operation>
  <apg-try-it operation-id="getPet"></apg-try-it>
  <apg-schema name="Pet" depth="2" with-example></apg-schema>
</apg-spec>

Jedna operacja wyrenderowana przez apg-operation, z przykładem ciała żądania i wygenerowanym przykładem odpowiedzi.

Otwórz zrzut ekranu w pełnym rozmiarze

Co obejmuje

Dokumenty AsyncAPI, Protobuf i GraphQL czyta ten sam parser co CLI, skompilowany do WebAssembly. Przykłady na żywo pokazują jedno API w OpenAPI, AsyncAPI, GraphQL i Protobuf.

OpenAPI 3.0 i 3.1Operacje, schematy, webhooki, Try it out z kluczami API, uwierzytelnianiem Basic i Bearer, OAuth 2.0 i OpenID Connect
Swagger 2.0Własne elementy, wybierane przez dokumentację automatycznie
AsyncAPI 3.0 i 3.1Serwery, kanały, operacje, wiadomości i bindingi
Protobuf i gRPCUsługi według rodzaju strumieniowania, wiadomości, enumy, przykłady grpcurl i klientów
GraphQLZapytania, mutacje, subskrypcje, typy i Try it out

Schemat GraphQL: zapytania, mutacje i subskrypcje oraz każdy typ.

Plik Protobuf z usługami gRPC i każdym rodzajem strumieniowania, w ciemnym motywie.

Instalacja

Zainstaluj @mykulyak/apigenie-docs, a potem zaimportuj przez import "@mykulyak/apigenie-docs". Żeby załadować jeden element, użyj jego punktu wejścia, na przykład import "@mykulyak/apigenie-docs/components/apg-operation".

npm install @mykulyak/apigenie-docs

Albo wygeneruj samodzielną witrynę z dokumentacją

Użyj apigenie-generator docs, gdy chcesz kompletnej statycznej witryny zamiast komponentów na istniejącą stronę. Używa tych komponentów i dodaje tłumaczenia, changelogi z Gita i pliki z przykładami.

apigenie-generator docs openapi.yaml events.asyncapi.yaml library.proto schema.graphql -o docs
cd docs && npm install && npm run build

Zastosowania

Publikuj dokumentację API

Osadź dokumentację API Wypróbuj przykłady na żywo