Custom tool to update the BP REST API documentation

bp-custom-swagger.php

<?php
/**
 * BP API Swagger UI Overrider.
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

if ( ! class_exists( 'WP_API_SwaggerUI' ) ) {
	require_once WP_PLUGIN_DIR . '/wp-api-swaggerui/wp-api-swaggerui.php';
}

class BP_API_SwaggerUI extends WP_API_SwaggerUI {
	public $response = array();

	public function __construct() {
		$this->swagger();
	}

	public function swagger() {
		global $wp_version;

		$this->response = array(
			'swagger'		      => '2.0',
			'info'			      => array(
				'title'		     => get_option( 'blogname' ) . ' API',
				'description'	 => get_option( 'blogdescription' ),
				'version'	     => $wp_version,
				'contact'	     => array(
					'email' => get_option( 'admin_email' )
				),
			),
			'host'			      => $this->getHost(),
			'basePath'		      => '/' . ltrim( rest_get_url_prefix(), '/' ),
			'tags'			      => [ [ 'name' => 'endpoint', 'description' => '' ] ],
			'schemes'		      => $this->getSchemes(),
			'paths'			      => $this->getPaths(),
			'definitions'         => $this->get_definitions(),
			'securityDefinitions' => $this->securityDefinitions()
		);
	}

	public function get_definitions() {
		$preload_paths = array( '/?context=help' );

		$preload_data = array_reduce(
			$preload_paths,
			'rest_preload_api_request',
			array()
		);

		$help = reset( $preload_data );
		$definitions = array();

		foreach ( $help['body']['routes'] as $route => $endpoint ) {
			if ( 0 === strpos( $route, '/buddypress/v1/' ) && isset( $help['body']['routes'][ $route ]['schema']['properties'] ) ) {
				$ep	   = $this->convertEndpoint( $route );
				$title = $help['body']['routes'][ $route ]['schema']['title'];
				$type  = $help['body']['routes'][ $route ]['schema']['type'];

				if ( ! isset( $definitions[ $title ] ) ) {
					$definitions[ $title ] = array(
						'type' => $type,
						'properties' => array(),
						'xml' => array( 'name' => $title ),
					);

					$required_props = wp_filter_object_list( $help['body']['routes'][ $route ]['schema']['properties'], array( 'required' => true ) );
					if ( $required_props ) {
						$definitions[ $title ]['required'] = array_keys( $required_props );
					}

					foreach ( $help['body']['routes'][ $route ]['schema']['properties'] as $prop => $def ) {
						$property = $this->buildParams( $prop, 'get', $ep, $def );
						unset( $property['name'], $property['in'], $property['collectionFormat'], $property['required'] );
						$definitions[ $title ]['properties'][ $prop ] = $property;
					}
				}
			}
		}
		
		return $definitions;
	}
}

bp-custom.php

<?php
/**
 * WP API Swagger UI Overrides.
 *
 * Unfortunately, this plugin is not providing schema definitions.
 * This file is fixing this lack.
 * 
 * Installation:
 * 1. Download and activate WP API Swagger @see https://wordpress.org/plugins/wp-api-swaggerui/.
 * 2. Check out latest BuddyPress trunk, activate it if not already done.
 * 3. Git pull BP REST API, activate it if not already done.
 * 4. Copy this file into `site.path/wp-content/plugins/`.
 * 5. Copy the bp-custom-swagger.php file into `site.path/wp-content/plugins/` (the same place).
 * 6. Go to site.url/wp-admin/options-general.php?page=swagger-ui.
 * 7. Select `buddypress/v1` as the 'API Basepath' and save changes.
 * 8. Click on the `Docs URL` link.
 * 9. You can navigate into the BP REST API endpoints more easily. PS: "Models" at the bottom of the page are schema definitions (the first table of each endpoint documentation page).
 * 10. @see https://developer.buddypress.org/bp-rest-api/reference/members/ and do the same for the new endpoints.
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

function imath_unhook_swagger_from_wp() {
	global $wp_filter;

	if ( isset( $wp_filter['wp']->callbacks ) ) {
		foreach ( $wp_filter['wp']->callbacks as $callback_priority => $callback_functions ) {
			foreach ( $callback_functions as $key_callback => $args_callback ) {
				if ( is_array( $args_callback['function'] ) && $args_callback['function'][0] instanceof WP_API_SwaggerUI ) {
					remove_action( 'wp', $args_callback['function'] );
				}
			}
		}
	}
}
add_action( 'wp', 'imath_unhook_swagger_from_wp', 0 );

function imath_hook_custom_swagger_to_wp() {
	if ( get_query_var( 'swagger_api' ) !== 'schema' ) {
	    return;
	}

	if (  ! in_array( 'wp-api-swaggerui/wp-api-swaggerui.php', get_option( 'active_plugins', array() ), true ) ) {
		wp_die( 'WP API SwaggerUI is not active.' );
	}

	require_once dirname( __FILE__ ) . '/bp-custom-swagger.php';
	$bpswagger = new BP_API_SwaggerUI();
	
	wp_send_json( $bpswagger->response );
}
add_action( 'wp', 'imath_hook_custom_swagger_to_wp', 11 );