WP OpenAPI

WP OpenAPI is a WordPress plugin that generates OpenAPI 3.1.0 compatible documentation for your WordPress REST APIs.

It has two main features.

1. Outputs OpenAPI 3.1.0 spec at /wp-json-openapi
2. Provides OpenAPI viewer using Stoplight's awesome Elements viewer

Screenshots

Usage

1. Download the latest zip archive from releases page and activate it.
2. You should see WP OpenAPI menu on the sidebar.
3. Click All to view all the endpoints or choose a namespace to view the endpoints registered in the namespace.

Optional Settings

WP OpenAPI has two optional settings -- Enable Try It and Enable Callback Discovery.

Both settings are turned off by default. You can enable them in Settings -> WP OpenAPI

Enable Try It: It enables Elements's TryIt feature. It lets you try the REST API endpoints.

Enable Callback Discovery: It shows you callback information about the endpoint you're viewing. It comes in handy if you want to look at the source code of the endpoint.

Extending

WP OpenAPI has the following filters to modify the output.

Name	Argument	Equivalent Filters Method
wp-openapi-filter-operations	Operation[]	AddOperationsFilter
wp-openapi-filter-paths	Path[]	AddPathsFilter
wp-openapi-filter-servers	Server[]	AddServersFilter
wp-openapi-filter-info	Info	AddInfoFilter
wp-openapi-filter-tags	Tag[]	AddTagsFilter
wp-openapi-filter-components	Array	AddComponentsFilter
wp-openapi-filters-elements-props	Array
wp-openapi-filters-schema-endpoint-permission	true

You can use individual filters by calling add_filter.

You can also use Filters.

Filters::getInstance()->addPathsFilter(function(array $paths, array $args) {
    if ($args['requestedNamespace'] === 'all) {
        foreach ($paths as $path) {
            foreach ($path->getOperations() as $operation) {
                $operation->setDescription('test');
            }
        }
    }
});

Using security field

Since there is no central place to add securitySchemes in WordPress, you can use the wp-openapi-filter-components filter to add them.

 add_filter('wp-openapi-filter-components', function(array $components) {
	$components['securitySchemes'] = [
		'api_key' => [
			'type' => 'apiKey',
			'name' => 'api_key',
			'in' => 'header',
		]
	];
	
	return $components;
 });

Now, you can use the security field in your REST API definition.

register_rest_route(
	$this->namespace,
	'/' . $this->rest_base . '/test',
	array(
		array(
			'methods'             => 'GET',
			'callback'            => array( $this, 'test' ),
			'args'                => array(
				'status' => array(
					'type' => 'string',
					'enum' => array( 'yes', 'no' ),
				),
				'credentials' => [
					'type' => 'object',
					'properties' => [
						'username' => ['type' => 'string'],
						'application_password' => ['type' => 'string'],
					]
				]
			),
			'security' => array(
				'api_key'=> array(),
			)
		),
	)
);

Export

WP OpenAPI comes with a WP CLI command to export a single HTML file.

You can use the file offline or host it on a webserver.

1. Install WP CLI
2. Open a terminal session and cd to your WordPress installtion directory.
3. Run wp openapi export --namespace=all --save_to=./export.html

Development

Getting Started

To get started, run the following commands:

npm i
composer install
npm start

See wp-scripts for more usage information.

Deploying

Prerequisites:

• Hub
• Write access to this repository

1. Run both npm i and composer install
2. Update the plugin version in wp-openapi.php and readme.txt
3. Update Tested up to in readme.txt if necessary.
4. Open a new PR and merge it.
5. Checkout main branch locally.
6. Run ./bin/release-to-github.sh. This will create a new release in Github
7. Run ./bin/release-plugin-to-dot-org.sh to release the new version to wp.org

You can also build a zip file for testing purposes by runnning ./bin/build-zip.sh

Todo

• Code clean up
• Write tests
• Make a publicly accessible endpoint
• Remove this dirty hack 😅