Contributing to the Discourse API documentation

[Discourse]

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:

1. From your home directory, clone the repository at https://github.com/discourse/discourse_api_docs:

   git clone https://github.com/discourse/discourse_api_docs
   

2. You should now have the discourse and discourse_api_docs folders 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:

1. From ~/discourse_api_docs/, run:

   npm install
   node server.js
   

2. 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

• Topics tagged dev-install
• Discourse GitHub Repository

Last edited by @hugh 2024-06-11T05:08:16Z

Check document

Perform check on document:

[srinivas.chilukuri]

How to report errors in discourse api documentation

Github repo for api documentation does not issues tab activated

[JammyDodger]

Hello and welcome @srinivas.chilukuri

You can report them on here. What seems to be the isssue?

[srinivas.chilukuri]

Reference : Discourse API Documentation Get a Group

Actions: Groups/ Get a Group

• In documentation path parameter is shown as id ,when queried the path doesn’t exist
• When reverse engineered same query via discourse UI the path parameter is group name and same works via API Key