projekt Cloud Native Computing Foundation (CNCF)

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:
Cloud Native Computing Foundation (CNCF)
Pisarz techniczny:
feloy
Nazwa projektu:
Zaktualizuj sposób, w jaki witryna Kubernetes obsługuje odwołania do interfejsu API
Długość projektu:
Standardowa długość (3 miesiące)

Opis projektu

Obecnie odwołania do interfejsu Kubernetes API to duże dokumenty HTML wygenerowane na podstawie specyfikacji Swagger za pomocą skryptów hostowanych poza repozytorium witryny, a następnie dodanych do tego repozytorium.

Z drugiej strony witryna z dokumentacją Kubernetes została stworzona we współpracy z Hugo na podstawie dokumentacji zapisanej w formacie Markdown w repozytorium witryny i motywu Dokumentów Hugo.

Celem tego projektu jest zintegrowanie generowania odwołań do interfejsu Kubernetes API z procesem tworzenia witryny z dokumentacją.

W szczególności skupimy się na krótkim kodzie Swaggerui obejmującym interfejs swagger-ui udostępniany przez motyw Dokumentów Hugo oraz na określonych narzędziach, które umożliwiają wstawianie części specyfikacji API w przepływie dokumentacji Kubernetes.

Potrzebne będą specjalne narzędzia, ponieważ swagger-ui może wygenerować pełną specyfikację opisaną w pliku swagger, ale nie jej części (patrz punkt 8). Interfejs Kubernetes API jest za duży, aby można go było wyświetlić tylko w jednej części (przykładowe dane wyjściowe). Rozważymy 2 podejścia:

  • Pierwsze podejście polega na utworzeniu kilku plików swagger, po jednym dla każdej grupy interfejsu API Kubernetes (core/v1, apps/v1, itd.) ze źródeł dostępnych w (10) i użyciu tych plików jako danych wejściowych sortcodes swaggerui w określonych miejscach na stronie internetowej dokumentacji Kubernetes.

  • Drugie podejście polega na utworzeniu narzędzia, które jako dane wejściowe otrzymuje pełny plik swagger interfejsu API Kubernetes (znajdujący się w (11)) i wyprowadza nowy plik swagger dla konkretnego punktu końcowego lub ograniczonej liczby punktów końcowych wraz z powiązanymi zasobami i definicjami, a następnie używa tych plików swagger jako danych wejściowych do skrótów swaggerui w określonych miejscach na stronie internetowej dokumentacji Kubernetes.

Źródła specyfikacji (10 i 11) znajdują się w innych repozytoriach niż źródła dokumentacji, dlatego musimy znaleźć sposób na ich automatyczne aktualizowanie w repozytorium dokumentacji po wprowadzeniu zmian.

Dokumentacja Kubernetes jest dostępna w różnych językach, dlatego zwrócić szczególną uwagę na możliwość opublikowania tłumaczeń dla dokumentacji Kubernetes API.