This is a guide for contributing to the official Discourse API documentation.
Required user level: Developer
Console access required
Do you want to contribute to the official API documentation at https://docs.discourse.org? This guide will explain step by step how to do it.
Summary
This documentation will guide you through the following steps:
- Setting up prerequisites.
- Cloning the Discourse API documentation repository.
- Editing the API documentation files.
- Viewing your changes locally.
- Creating a pull request.
Prerequisites
You must have a Discourse development installation. If you don’t have one, follow the guide that suits your environment in these topics.
Cloning the Discourse API docs repository
Assuming your Discourse development installation is inside your home directory ~/, proceed with the following steps to clone the repository:
-
From your home directory, clone the repository at https://github.com/discourse/discourse_api_docs:
git clone https://github.com/discourse/discourse_api_docs -
You should now have the
discourseanddiscourse_api_docsfolders side by side:~/discourse/ ~/discourse_api_docs/
Editing the API documentation files
You must edit the documentation directly from ~/discourse/spec/requests/api/.
- See the folder on GitHub: discourse/spec/requests/api at main · discourse/discourse · GitHub
After editing the documentation files, run the following command from ~/discourse/:
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yaml
The documentation will be generated using rswag and copied into ~/discourse_api_docs/.
Viewing your changes locally
To view your updated documentation, follow these steps:
-
From
~/discourse_api_docs/, run:npm install node server.js -
Browse to http://localhost:3001 to see the updated documentation.
Creating a pull request
Once you verify that everything looks good, create a pull request from the discourse/discourse repository (not the Discourse API Docs repository).
Common issues and solutions
Reporting errors in Discourse API documentation
If you encounter issues or errors in the Discourse API documentation, please report them on the Discourse Meta forum - you can follow the bug report guide to help you do this effectively.
Additional resources
Last edited by @hugh 2024-06-11T05:08:16Z
Check document
Perform check on document:
出了什么问题？