search

moon0326 / wp-openapi

19 stars 5 forks source link

readme

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

screenshot

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-security Array AddSecurityFilter
wp-oepnapi-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');
            }
        }
    }
});

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:

  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