How to contribute to the Discourse API Docs


(Blake Erickson) #1

Contributions to the Discourse API Docs are welcome! Start by cloning the discourse_api_docs repo.

To edit the api docs, edit the swagger.yml file (not the json file).

To view your changes locally, run:

npm install
node server.js

Browse to localhost:3001 to see the pretty docs.

Before you push your changes or create a PR convert the yml file to json:

node tojson.js

Then you can commit your changes and create a PR. You need to convert the yml file to json before you create a PR because we are using github pages to host the static doc website which reads the json file.

Schema Generator

To aid in writing the yml responses in the swagger.yml file use this command to
convert actual json responses to a yml schema file:

node toschema.js <input file> <output file>


node toschema.js responses/topics/topic_respones.json definitions/topics/topic_response.yml

This will convert a json response into json schema and then convert the schema
to yml.

Discourse API Documentation