Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Cloud Native Computing Foundation (CNCF)
- Redator técnico:
- feliz
- Nome do projeto:
- Atualizar como o site do Kubernetes exibe referências de API
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Atualmente, as referências da API Kubernetes são grandes documentos HTML gerados com base nas especificações do Swagger por scripts hospedados fora do repositório do site e adicionados a esse repositório.
Por outro lado, o site de documentação do Kubernetes foi criado com o Hugo usando a documentação escrita no formato Markdown no repositório do site, usando o tema Docsy Hugo.
O objetivo deste projeto é integrar a geração das referências da API Kubernetes no processo de criação do site de documentação.
Vamos nos concentrar mais no código curto swaggerui, no wrapper swagger-ui (link em inglês), fornecido pelo tema Docsy Hugo e em ferramentas específicas, permitindo a inserção de partes da especificação da API no fluxo da documentação do Kubernetes.
Ferramentas específicas serão necessárias, já que o swagger-ui consegue gerar a especificação completa descrita em um arquivo swagger, mas não em partes dele (consulte a seção 8). A API Kubernetes é muito grande para ser mostrada em uma parte só (um exemplo de saída). Vamos considerar duas abordagens:
a primeira abordagem é criar vários arquivos swagger, um para cada grupo da API Kubernetes (core/v1, apps/v1, ...) a partir de fontes disponíveis em (10) e usar esses arquivos como entrada de códigos de classificação swaggerui em locais específicos no site de documentação do Kubernetes.
A segunda abordagem é criar uma ferramenta que receba como entrada o arquivo swagger completo da API Kubernetes encontrada em (11) e gere um novo arquivo swagger para um endpoint específico ou um número limitado de endpoints e os recursos e definições associados dele. Depois, use esses arquivos swagger como entrada de códigos curtos swaggerui em locais específicos do site de documentação do Kubernetes.
Como as fontes das especificações (10 e 11) residem em outros repositórios que não as fontes da documentação, precisamos encontrar uma maneira de atualizá-las automaticamente no repositório de documentação quando elas forem alteradas.
Como a documentação do Kubernetes está disponível em diferentes idiomas, vamos prestar atenção especial à possibilidade de publicar traduções para a referência da API Kubernetes.