Este é um guia para contribuir com a documentação oficial da API do Discourse.
Nível de usuário necessário: Desenvolvedor
Acesso ao console necessário
Você deseja contribuir com a documentação oficial da API em https://docs.discourse.org? Este guia explicará, passo a passo, como fazê-lo.
Resumo
Esta documentação o guiará pelas seguintes etapas:
- Configurar os pré-requisitos.
- Clonar o repositório da documentação da API do Discourse.
- Editar os arquivos de documentação da API.
- Visualizar suas alterações localmente.
- Criar um pull request.
Pré-requisitos
Você deve ter uma instalação de desenvolvimento do Discourse. Se não tiver uma, siga o guia adequado ao seu ambiente nestes tópicos (Topics tagged dev-install).
Clonando o repositório da documentação da API do Discourse
Supondo que sua instalação de desenvolvimento do Discourse esteja dentro do seu diretório inicial ~/, proceda com as seguintes etapas para clonar o repositório:
-
Do seu diretório inicial, clone o repositório em https://github.com/discourse/discourse_api_docs:
git clone https://github.com/discourse/discourse_api_docs -
Agora você deve ter as pastas
discourseediscourse_api_docslado a lado:~/discourse/ ~/discourse_api_docs/
Editando os arquivos de documentação da API
Você deve editar a documentação diretamente em ~/discourse/spec/requests/api/.
- Veja a pasta no GitHub: discourse/spec/requests/api at main · discourse/discourse · GitHub
A documentação da API de plugins também pode ser contribuída por meio de arquivos de spec localizados em plugins/*/spec/requests/api/.
Após editar os arquivos de documentação, execute o seguinte comando em ~/discourse/:
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
A documentação será gerada usando rswag e copiada para ~/discourse_api_docs/.
Em seguida, converta o arquivo YAML para JSON em ~/discourse_api_docs/:
npm install
node tojson.js
Visualizando suas alterações localmente
Para visualizar sua documentação atualizada, siga estas etapas:
-
Em
~/discourse_api_docs/, execute:npm install node server.js -
Acesse http://localhost:3001 para ver a documentação atualizada.
Criando um pull request
Uma vez que você verifique que tudo está correto, crie um pull request a partir do repositório discourse/discourse (não do repositório Discourse API Docs).
O repositório discourse_api_docs é atualizado automaticamente diariamente por meio de um fluxo de trabalho do GitHub Actions que regenera a especificação OpenAPI a partir das últimas especificações do núcleo do Discourse. Você não precisa enviar um PR separado para esse repositório.
Problemas comuns e soluções
Relatando erros na documentação da API do Discourse
Se você encontrar problemas ou erros na documentação da API do Discourse, por favor, relate-os no fórum Discourse Meta — você pode seguir o guia de relatórios de bugs para ajudá-lo a fazer isso de forma eficaz.
Qual parece ser o problema?