# Contributing to the Discourse API documentation

**URL:** <https://meta.discourse.org/t/contributing-to-the-discourse-api-documentation/56693>\
**Category:** Contributing\
**Tags:** rest-api, how-to\
**Created:** [2월 1, 2017, 5:22오전 UTC](https://meta.discourse.org/t/contributing-to-the-discourse-api-documentation/56693 "2017-02-01T05:22:51Z")\
**Posts on this page:** 1\
**Showing post:** 1

<div class="post-metadata">

**Author:** ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)\
**Post date:** [2월 1, 2017, 5:22오전 UTC](https://meta.discourse.org/t/contributing-to-the-discourse-api-documentation/56693/1 "2017-02-01T05:22:51Z")

</div>

> 🔖 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](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](https://meta.discourse.org/tags/c/documentation/10/dev-install).

## 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](https://github.com/discourse/discourse_api_docs):

2. You should now have the `discourse` and `discourse_api_docs` folders side by side:

## 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](https://github.com/discourse/discourse/tree/main/spec/requests/api)

Plugin API documentation can also be contributed via spec files located in `plugins/*/spec/requests/api/`.

After editing the documentation files, run the following command from `~/discourse/`:

```bash
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml

```

The documentation will be generated using [rswag](https://github.com/rswag/rswag) and copied into `~/discourse_api_docs/`.

Then, convert the YAML file to JSON from `~/discourse_api_docs/`:

```bash
npm install
node tojson.js

```

## Viewing your changes locally

To view your updated documentation, follow these steps:

1. From `~/discourse_api_docs/`, run:

2. Browse to [http://localhost:3001](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).

💡 The `discourse_api_docs` repository is automatically updated daily via a GitHub Actions workflow that regenerates the OpenAPI spec from the latest Discourse core specs. You do not need to submit a separate PR to that 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](https://meta.discourse.org) - you can follow the [bug report guide](https://meta.discourse.org/t/creating-bug-reports-for-discourse-on-meta/33070) to help you do this effectively.

## Additional resources

- [Topics tagged dev-install](https://meta.discourse.org/tags/c/documentation/10/dev-install)
- [Discourse GitHub Repository](https://github.com/discourse/discourse)

> Last edited by @hugh 2024-06-11T05:08:16Z
> 
> > **Check document**
> >
> > Perform check on document:

---

_[View the full topic](https://meta.discourse.org/t/contributing-to-the-discourse-api-documentation/56693)._