{"id":29150157,"url":"https://github.com/humanmade/restsplain","last_synced_at":"2025-06-30T23:09:45.129Z","repository":{"id":48501945,"uuid":"80136425","full_name":"humanmade/Restsplain","owner":"humanmade","description":"WordPress REST API documentation generator","archived":false,"fork":false,"pushed_at":"2021-07-22T14:54:17.000Z","size":5967,"stargazers_count":157,"open_issues_count":23,"forks_count":18,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-06-30T16:14:53.873Z","etag":null,"topics":["create-react-app","react","wordpress","wordpress-api","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/humanmade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-26T17:18:51.000Z","updated_at":"2025-02-20T19:30:17.000Z","dependencies_parsed_at":"2022-08-31T08:12:16.653Z","dependency_job_id":null,"html_url":"https://github.com/humanmade/Restsplain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/humanmade/Restsplain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2FRestsplain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2FRestsplain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2FRestsplain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2FRestsplain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/humanmade","download_url":"https://codeload.github.com/humanmade/Restsplain/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2FRestsplain/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262864258,"owners_count":23376461,"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":["create-react-app","react","wordpress","wordpress-api","wordpress-plugin"],"created_at":"2025-06-30T23:09:44.293Z","updated_at":"2025-06-30T23:09:45.056Z","avatar_url":"https://github.com/humanmade.png","language":"JavaScript","readme":"\u003ctable width=\"100%\" style=\"width:100%\"\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd align=\"left\" width=\"70%\"\u003e\n\t\t\t\u003ch1 style=\"border:0;margin-bottom:0;\"\u003eRestsplain\u003c/h1\u003e\n\t\t\tSuper fast WordPress REST API docs that update with your site.\n\t\t\u003c/td\u003e\n\t\t\u003ctd align=\"center\" width=\"30%\"\u003e\n\t\t\t\u003cimg src=\"https://hmn.md/content/themes/hmnmd/assets/images/hm-logo.svg\" width=\"100\" /\u003e\n\t\t\u003c/td\u003e\n\t\u003c/tr\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd\u003e\n\t\t\tA \u003cstrong\u003e\u003ca href=\"https://hmn.md/\"\u003eHuman Made\u003c/a\u003e\u003c/strong\u003e project. Maintained by @roborourke.\n\t\t\u003c/td\u003e\n\t\t\u003ctd\u003e\u003c/td\u003e\n\t\u003c/tr\u003e\n\u003c/table\u003e\n\nThe WordPress REST API provides much of it's own documentation via it's schema.\nThis plugin contains a React app that consumes the schema data to generate a \nblazing fast documentation site.\n\n1. Add and edit high level documentation pages\n2. Automatic discovery and display of all custom endpoints\n3. Make API requests direct from the documentation!\n\n![Restsplain running on TwentySeventeen](https://hmn.md/uploads/sites/2/2017/02/Screenshot-2017-02-20-01.23.08.png)\n\n## Installation\n\nUpload the plugin to your plugins directory and activate it.\n\nYou'll need to refresh your permalinks to use the built in URL by visiting\nthe permalinks settings page in the admin.\n\nOnce you've done that browse to `http://your-site.com/api-docs/` and you're \ndone!\n\n## Configuration\n\nHopefully you won't need to do much configuration with Restsplain however\nthere are a number of filters you can use to change it's behaviour.\n\n### Default URL\n\nThe docs will by default show at `/api-docs/` however you can modify this\nusing the filter:\n\n```php\n\u003c?php\nadd_filter( 'restsplain_docs_base', function() {\n\treturn '/api/docs';\n} );\n```\n\n### Default content\n\nIn the admin you'll see a new post type called \"API Docs\". Default pages \nwill be created for you if you don't add any before visiting the docs however \nyou can edit these and add to them or remove them afterwards.\n\nThe top level pages are:\n\n1. Global Parameters\n2. Linking and Embedding\n3. Errors\n\nIn addition a page for each default authentication type and each route will be \nadded.\n\nWhen you create a page for a route you should make the title exactly the same\nas the route key in the schema eg. `/wp/v2/posts/(?P\u003cid\u003e[\\d]+)`.\n\nIf the title does not match then the page is treated as top level documentation\nand will appear at the top of the menu.\n\n#### Adding default pages\n\nDevelopers can add support for Restsplain in one of 2 ways:\n\n1. Filter the schema output with the `rest_index` hook and add a `description`\n   and optional `excerpt` key/value to each route object.\n2. Add a file with the namespace `Restsplain` and call\n   `add_default_page( $slug, $page )`\n \n```php\n\u003c?php\nnamespace Restsplain;\n\n// Accepts just a string\nadd_default_page( '/wp/v2/users', __( 'Fetch or create Users.' ) );\n\n// Or an array with keys title, excerpt and content\nadd_default_page( 'oauth1', array(\n\t'title'   =\u003e __( 'Oauth 1.0a' ),\n\t'excerpt' =\u003e __( 'Endpoints for authenticating requests with Oauth 1.0a' ),\n\t'content' =\u003e '\u003cp\u003e...\u003c/p\u003e', \n) );\n```\n\nPages will be created in the admin that can then be edited.\n\n### Theming\n\nBy default Restsplain is written to use as much of your site's existing styles\nas possible so your fonts and typography should all be respected. In addition\nif your theme supports a custom logo it will be displayed in the header.\n\nThe standard calls to `wp_head()` and `wp_footer()` are present in the template \nso adding your own CSS is simple. Everything is styled under the `.restsplain` \nnamespace.\n\n\u003e **NOTE:** You will more than likely have to add some styles if your theme does\nnot have rules for tables are global element rules for example.\n\n#### highlight.js\n\nYou may wish to change the code highlighter to a different theme to suit your \ndesign.\n\nCode highlighting is done using [highlight.js](https://highlightjs.org/) so you\ncan provide the name of any one of its 77 styles. You can find them at\nhttps://highlightjs.org/static/demo/\n\n```php\n\u003c?php\nadd_filter( 'restsplain_config', function( $config ) {\n\t$config['codeTheme'] = 'docco';\n\treturn $config;\n} );\n```\n\n#### Logo\n\nYour custom logo will be used by default if your theme supports it and you have\none uploaded. Otherwise you can use a filter to change it to some other image URL.\n\n```php\n\u003c?php\nadd_filter( 'restsplain_config', function( $config ) {\n\t$config['logo'] = 'http://www.fillmurray.com/g/200/200';\n\treturn $config;\n} );\n```\n\n## Localisation\n\nThe plugin is translation ready including the React component. If you'd like to\nprovide a translation let us know!\n\n## Note to developers\n\nThe docs generated by an automated tool such as this will only be as good as the\ndocs you build into your API endpoint definitions. Learn about and add proper\nschemas to your plugin or theme endpoints:\n\nhttps://developer.wordpress.org/rest-api/extending-the-rest-api/schema/\n\n## There will be bugs, there will\n\nIf you're interested in contributing to and improving Restsplain (and it will need it!)\nthere are a few things you need to know besides React:\n\n### Running the app locally\n\nRestsplain is built using [`create-react-app`](https://github.com/facebookincubator/create-react-app)\nwhich is a great way to get up and running quickly with React.\n\nThe app itself is in the `app` folder of the plugin.\n\nClone the repo and grab everything you need to work on the React app.\n\n```bash\ngit clone git@github.com:humanmade/Restsplain.git\ncd Restsplain/app\nnpm install # or yarn\nnpm start # or yarn start\n```\n\n### Styling tips\n\nThe built in CSS is intentionally low level and layout focused. Ideally the plugin\nshould look as native to the site it is running on as possible with minimal input\nrequired from the site owner.\n\nStyling is done using Sass (compiled separately to the final bundle, see the\n`package.json` npm scripts for details) which is compiled and the resulting\nCSS then imported via the JavaScript. Webpack takes care of processing this\nand generating the final file.\n\n### Debug mode\n\nAdd `define( 'RESTSPLAIN_DEBUG', true );` to your config file to make the plugin\nuse the development files served from `http://localhost:3000`\n\n**NOTE:** Currently the hotloading doesn't work in the WordPress context so if\nyou know how to fix it create a pull request!\n\n## License\n\nRestsplain is licensed under the GPLv3 or later.\n\n## Credits\n\nCreated by Human Made for easing the pain of keeping up to date documentation\nfor our new API driven WordPress world.\n\nWritten and maintained by [Robert O'Rourke](https://github.com/roborourke) \n\n\nInterested in joining in on the fun? [Join us, and become human!](https://hmn.md/is/hiring/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanmade%2Frestsplain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumanmade%2Frestsplain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanmade%2Frestsplain/lists"}