discourse/discourse_api_docs

Name: discourse_api_docs

Owner: Discourse

Description: Discourse API Documentation

Created: 2017-02-02 21:11:48.0

Updated: 2018-05-23 21:15:31.0

Pushed: 2018-05-23 21:15:29.0

Homepage: http://docs.discourse.org/

Size: 508

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Discourse API Documentation

To view the the Discourse API Documentation you can visit:

http://docs.discourse.org/

Here is an example of what the ReDoc site looks like:

Postman

In addition to the docs site, you can also import the postman json files into postman to test making real API calls and see the json output.

Postman files:

• environment
• collection

Start by importing the environment json file. After you import it be sure to change the base_url, api_username, and api_key values to match your discourse instance.

Now you can import the collection json file and start making API requests.

Here is a demo:

Contributing

Contributions are welcome! Start by cloning the repo.

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

To view your changes locally, run:

install
 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:

 tojson.js

Then you can commit your changes and create a PR. This is because we are using github pages to host the static doc website.

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:

 toschema.js <input file> <output file>

Example:

 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.