{"id":18708019,"url":"https://github.com/discourse/discourse_api_docs","last_synced_at":"2025-10-15T18:05:11.179Z","repository":{"id":39546172,"uuid":"80769160","full_name":"discourse/discourse_api_docs","owner":"discourse","description":"Discourse API Documentation","archived":false,"fork":false,"pushed_at":"2024-04-26T06:54:33.000Z","size":1438,"stargazers_count":37,"open_issues_count":3,"forks_count":38,"subscribers_count":23,"default_branch":"main","last_synced_at":"2024-05-09T09:23:24.989Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.discourse.org/","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/discourse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-02T21:11:48.000Z","updated_at":"2024-05-30T02:57:18.601Z","dependencies_parsed_at":"2023-12-09T12:26:26.111Z","dependency_job_id":"68bb2d06-d903-47ee-903f-f301d070d66b","html_url":"https://github.com/discourse/discourse_api_docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fdiscourse_api_docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fdiscourse_api_docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fdiscourse_api_docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discourse%2Fdiscourse_api_docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/discourse","download_url":"https://codeload.github.com/discourse/discourse_api_docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248553545,"owners_count":21123470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T12:21:00.995Z","updated_at":"2025-10-15T18:05:06.135Z","avatar_url":"https://github.com/discourse.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discourse API Documentation\n\n![automatic updates](https://github.com/discourse/discourse_api_docs/actions/workflows/update_docs.yml/badge.svg)\n\nTo view the the Discourse API Documentation you can visit:\n\n  https://docs.discourse.org/\n\n### Contributing\n\nContributions are welcome! Start by cloning this repo as well as the\n[discourse](https://github.com/discourse/discourse) repo.\n\n\nThe API docs are automatically generated from the discourse repo using a tool\ncalled rswag.\n\nYou can generate the openapi.yml file that is located in this repo by running\nthis command from inside of your discourse repo directory:\n\n\n```\nrake rswag:specs:swaggerize \u0026\u0026 cp openapi/openapi.yaml ~/code/discourse_api_docs/openapi.yml\n```\n\nPlease do not manually edit the openapi.yml or openapi.json files located in\nthis repo. These files must be edited from the rswag files located in\n\nhttps://github.com/discourse/discourse/tree/main/spec/requests/api\n\nTo view your changes locally, run:\n\n```\nnpm install\nnode server.js\n```\n\nBrowse to http://localhost:3001 to see the pretty docs.\n\nBefore you push your changes or create a PR convert the yml file to json:\n\n```\nnode tojson.js\n```\n\nTo verify converting to json worked correctly, please run:\n\n```\nnode server.js json\n```\n\nwhich will load the json file directly instead of live converting the yml file\nto json. Now browse to http://localhost:3001 and verify your changes still look\nokay.\n\nThen you can commit your changes and create a PR. This is because we are using\ngithub pages to host the static doc website.\n\n### Automatic openapi.yml generation\n\nIf you are changing multiple API specs in the core Discourse repo, then you can use the `bundle exec rake autospec:swagger` rake task to watch for changes to files in the `spec/requests/api` directory. When a change is detected the swaggerize rake task command is run, the openapi.yml file is generated, and node tojson.js is run.\n\nThis can all be done while the local API docs server is running for live updates every time API spec files are changed.\n\n### Schema Generator\n\nTo aid in writing the yml responses in the swagger.yml file use this command to\nconvert actual json responses to a yml schema file:\n\n```\nnode toschema.js \u003cinput file\u003e \u003coutput file\u003e\n```\n\nExample:\n\n```\nnode toschema.js responses/topics/topic_respones.json definitions/topics/topic_response.yml\n```\n\nThis will convert a json response into json schema and then convert the schema\nto yml.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscourse%2Fdiscourse_api_docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiscourse%2Fdiscourse_api_docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscourse%2Fdiscourse_api_docs/lists"}