SwaggerUI for WordPress REST API

Description

SwaggerUI used to make WordPress REST API endpoint have a interactive UI, so we can check our API endpoint directly from the website it self.

Features

• Support for GET, POST, PUT, PATCH and DELETE request methods
• Support for Auth Basic authorization method
• Support for Bearer token (Authorization header) authorization method
• Choose which authorization methods (Basic / Bearer) appear in the Swagger UI Authorize dialog
• Output as Swagger 2.0 (default) or OpenAPI 3.0.3
• Option to include or omit the site admin contact email in the generated schema
• Choose which namespace API that will be used on the SwaggerUI

Requirements

• Your website should not block support of WordPress default REST API
• WordPress 4.7 or later (REST API v2)
• PHP 7.4 or later

Installation

Manual Installation

• Clone this repository
• Run npm install
• Run npm run build
• Copy all files into your wp-content/plugins/wp-api-swaggerui folder

Automatic Installation

1. Log in and navigate to Plugins > Add New.
2. Type “WP API SwaggerUI” into the Search and hit Enter.
3. Locate the WP API SwaggerUI plugin in the list of search results and click Install Now.
4. Once installed, click the Activate link.

Usage

After installing and activating the plugin, from your WordPress admin dashboard, access settings and then you will be able to see the Swagger option. Click that to access the Swagger Setting page.

Changing API Basepath

From the Swagger Setting page, choose between the API Basepath options displayed on the select menu, then click on the Save Changes button. Accessing the Docs URL you will be able to see the Swagger UI configured for the chosen endpoint.

Access Swagger UI

You can see Swagger Docs URL accessing:

• http://example.com/rest-api/docs/

Settings

The Swagger Setting page (Settings → Swagger) also offers:

• Authentication — pick which methods (Basic / Bearer) appear in the Swagger UI Authorize dialog. Bearer requires a token plugin (e.g. JWT) to validate requests.
• OpenAPI Version — output as Swagger 2.0 (default) or OpenAPI 3.0.3.
• Contact Email — include or omit the site admin email as the API contact. Override via the swagger_api_contact_email filter.

Authorization

On WordPress 5.6+, the Swagger UI Authorize (Basic) prompt is handled by WordPress' native Application Passwords: enter your WordPress username and an application password (not your login password). WooCommerce consumer key/secret pairs still authenticate here as well. On older WordPress the plugin's built-in Basic Auth handles the username and password.

REST API Customization

To customize how your created endpoints are shown at Swagger, here is an example with all the possible arguments you can add to your route:

GET

register_rest_route(
    'pet',
    '/(?P<petId>\d+)',
    [
        'methods'              => 'GET',
        'callback'             => $service->get_callback(),
        'summary'              => 'Find pet by ID',
        'description'          => 'Returns a single pet',
        'tags'                 => ['Pets'],
        'produces'             => ['application/json', 'application/xml'],
        'responses'            => [
            '200' => [
                'description' => 'successful operation',
                'schema'      => [
                    'type'       => 'object',
                    'required'   => ['name', 'photoUrls'],
                    'properties' => [
                        'id' => [
                            'type'   => 'integer',
                            'format' => 'int64',
                        ],
                        'name' => [
                            'type'    => 'string',
                            'example' => 'doggie',
                        ],
                        'status' => [
                            'type'        => 'string',
                            'description' => 'pet status in the store',
                            'enum'        => ['available', 'pending', 'sold']
                        ]
                    ],
                    'example'    => [
                        'id'     => 1,
                        'name'   => 'doggie',
                        'status' => ' available'
                    ],
                    'xml' => [
                        'name' => 'Pet'
                    ]
                ]
            ],
            '400' => [
                'description' => 'Invalid ID supplied'
            ],
            '404' => [
                'description' => 'Pet not found'
            ]

        ],
        'args'                 => [
            'petId'   => [
                'in'          => 'path',
                'description' => 'ID of pet to return',
                'required'    => true,
                'type'        => 'integer',
                'format'      => 'int64'
            ]
        ],
        'permission_callback'  => '__return_true'
    ]
)

POST

register_rest_route(
    'user',
    '/',
[
  'methods'              => 'POST',
  'callback'             => $service->get_callback(),
  'summary'              => 'Create user',
  'description'          => 'This can only be done by the logged in user.',
  'consumes'             => ['application/json'],
  'produces'             => ['application/json', 'application/xml'],
  'responses'            => [
      'default' => [
          'description' => 'successful operation',
      ]
  ],
  'args'                 => [
      'body'   => [
          'in'          => 'body',
          'description' => 'Created user object',
          'required'    => true,
          'type'        => 'object',
          'schema'      => [
              'type'       => 'object',
              'properties' => [
                  'id' => [
                      'type'   => 'integer',
                      'format' => 'int64',
                  ],
                  'username' => [
                      'type' => 'string'
                  ],
                  'email' => [
                      'type' => 'string'
                  ],
                  'password' => [
                      'type' => 'string'
                  ],
              ],
              'example' => [
                  'id'       => 0,
                  'username' => 'string',
                  'email'    => 'string',
                  'password' => 'string',
              ]
          ]
      ]
  ],
  'permission_callback'  => '__return_true'
]
)

These examples were based on the defaults presented at Swagger Editor

Note: For POST/PUT/PATCH routes, registered JSON args are automatically combined into a single request body — you don't need to define an explicit body arg. Nested object/array schemas (with enum, required, format, default) are preserved. File uploads stay on multipart/form-data.

Guide

If you need help undesrtadning any of of the parameters used on this documentation, please refer to Swagger Documentation.
Here is some useful links:

• Adding Examples
• Describing Responses