https://github.com/humanmade/restsplain
WordPress REST API documentation generator
https://github.com/humanmade/restsplain
create-react-app react wordpress wordpress-api wordpress-plugin
Last synced: 4 months ago
JSON representation
WordPress REST API documentation generator
- Host: GitHub
- URL: https://github.com/humanmade/restsplain
- Owner: humanmade
- License: gpl-3.0
- Created: 2017-01-26T17:18:51.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-07-22T14:54:17.000Z (over 4 years ago)
- Last Synced: 2025-06-30T16:14:53.873Z (4 months ago)
- Topics: create-react-app, react, wordpress, wordpress-api, wordpress-plugin
- Language: JavaScript
- Homepage:
- Size: 5.69 MB
- Stars: 157
- Watchers: 31
- Forks: 18
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Restsplain
Super fast WordPress REST API docs that update with your site.
A Human Made project. Maintained by @roborourke.
The WordPress REST API provides much of it's own documentation via it's schema.
This plugin contains a React app that consumes the schema data to generate a
blazing fast documentation site.
1. Add and edit high level documentation pages
2. Automatic discovery and display of all custom endpoints
3. Make API requests direct from the documentation!
## Installation
Upload the plugin to your plugins directory and activate it.
You'll need to refresh your permalinks to use the built in URL by visiting
the permalinks settings page in the admin.
Once you've done that browse to `http://your-site.com/api-docs/` and you're
done!
## Configuration
Hopefully you won't need to do much configuration with Restsplain however
there are a number of filters you can use to change it's behaviour.
### Default URL
The docs will by default show at `/api-docs/` however you can modify this
using the filter:
```php
[\d]+)`.
If the title does not match then the page is treated as top level documentation
and will appear at the top of the menu.
#### Adding default pages
Developers can add support for Restsplain in one of 2 ways:
1. Filter the schema output with the `rest_index` hook and add a `description`
and optional `excerpt` key/value to each route object.
2. Add a file with the namespace `Restsplain` and call
`add_default_page( $slug, $page )`
```php
__( 'Oauth 1.0a' ),
'excerpt' => __( 'Endpoints for authenticating requests with Oauth 1.0a' ),
'content' => '
...
',
) );
```
Pages will be created in the admin that can then be edited.
### Theming
By default Restsplain is written to use as much of your site's existing styles
as possible so your fonts and typography should all be respected. In addition
if your theme supports a custom logo it will be displayed in the header.
The standard calls to `wp_head()` and `wp_footer()` are present in the template
so adding your own CSS is simple. Everything is styled under the `.restsplain`
namespace.
> **NOTE:** You will more than likely have to add some styles if your theme does
not have rules for tables are global element rules for example.
#### highlight.js
You may wish to change the code highlighter to a different theme to suit your
design.
Code highlighting is done using [highlight.js](https://highlightjs.org/) so you
can provide the name of any one of its 77 styles. You can find them at
https://highlightjs.org/static/demo/
```php