class OpenApiUi in OpenAPI UI 8

Defines a render element for OpenApi Doc display librarys.

This display element will act as a warpper for the ui element. The rendering process will use the library's plugin in order to allow for the plugin to control and extend the way the docs are being rendered.

The api docs can be supplied to the render element in a few different ways to the `#openapi_schema` property. They can either be supplied as any of the following.

• An array: An array containing the docs of the module which conforms to the OpenAPI schema. The array will be converted to json and exported during rendering.
• A url object: The url or path to a complient schema document.
• A url string: If a string is given, it will be converted to a url object.
• A file object: A drupal file object may be passed here. Checks will be performed to ensure that the doc is accessible to the user. The private url of the doc will ultimately be used by the ui, effectivly having the file object converted into its private url.
• A callback function: The docs can be implemented via a callback. The callback will be passed the render element and as a result should take exactly one paramter, an array, and return either an array with openapi complient schema or a url for the schema.

Doc library plugins may only support specific formats for the openapi docs. They may also support additional properties on this render element which can be used to control the display of the ui and allow for configuration of the resulting element.

Properties:

• #openapi_ui_plugin: A plugin instance, or the machine name of the desired plugin.
• #openapi_schema: The api specifications to use when building the docs ui. This property can have a few options. See the above for details.

Usage example:

$form['api_docs'] = [
  '#type' => 'openapi_ui',
  '#openapi_ui_plugin' => 'swagger',
  '#openapi_schema' => 'https://example.com/openapi',
];

Plugin annotation

@RenderElement("openapi_ui");

Hierarchy

• class \Drupal\Component\Plugin\PluginBase implements DerivativeInspectionInterface, PluginInspectionInterface
  • class \Drupal\Core\Plugin\PluginBase uses DependencySerializationTrait, MessengerTrait, StringTranslationTrait
    • class \Drupal\Core\Render\Element\RenderElement implements ElementInterface
      • class \Drupal\openapi_ui\Element\OpenApiUi

File

src/Element/OpenApiUi.php, line 56

Namespace

Drupal\openapi_ui\Element

class OpenApiUi extends RenderElement {

  /**
   * {@inheritdoc}
   */
  public function getInfo() {
    $class = get_class($this);
    return [
      '#pre_render' => [
        [
          $class,
          'preRenderOpenApiUi',
        ],
      ],
    ];
  }

  /**
   * Provides markup for associating a tray trigger with a tray element.
   *
   * A tray is a responsive container that wraps renderable content. Trays
   * present content well on small and large screens alike.
   *
   * @param array $element
   *   A renderable array.
   *
   * @return array
   *   A renderable array.
   */
  public static function preRenderOpenApiUi(array $element) {
    $messenger = \Drupal::service('messenger');
    $plugin = $element['#openapi_ui_plugin'];

    // If the plugin id was passed, get the plugin instance.
    if (is_string($plugin) && !empty($plugin)) {
      $ui_plugin_manager = \Drupal::service('plugin.manager.openapi_ui.ui');
      $plugin = $ui_plugin_manager
        ->createInstance($plugin);
      $element['#openapi_ui_plugin'] = $plugin;
    }
    if (!$plugin instanceof OpenApiUiInterface) {
      $messenger
        ->addError(t('Unknown OpenAPI UI plugin being used.'));
      return $element;
    }
    $schema = $element['#openapi_schema'];

    // If a callback was passed, execute it to get a string, array, or url.
    if (is_callable($schema)) {
      $schema = call_user_func($schema, $element);
      $element['#openapi_schema'] = $schema;
    }

    // If the schema is a string, convert it to a URL object.
    if (is_string($schema)) {
      $schema = Url::fromUri($schema);
      $element['#openapi_schema'] = $schema;
    }

    // If schema is not a complient array or a URL, quit rendering.
    if (!(is_array($schema) || $schema instanceof Url)) {
      $messenger
        ->addError(t('Invalid schema source provided.'));
      return $element;
    }
    $element['#tree'] = TRUE;
    $element['ui'] = $plugin
      ->build($element);
    return $element;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property	An array of entity type IDs keyed by the property name of their storages.
DependencySerializationTrait::$_serviceIds	protected	property	An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep	public	function		1
DependencySerializationTrait::__wakeup	public	function		2
MessengerTrait::$messenger	protected	property	The messenger.	29
MessengerTrait::messenger	public	function	Gets the messenger.	29
MessengerTrait::setMessenger	public	function	Sets the messenger.
OpenApiUi::getInfo	public	function	Returns the element properties for this element. Overrides ElementInterface::getInfo
OpenApiUi::preRenderOpenApiUi	public static	function	Provides markup for associating a tray trigger with a tray element.
PluginBase::$configuration	protected	property	Configuration information passed into the plugin.	1
PluginBase::$pluginDefinition	protected	property	The plugin implementation definition.	1
PluginBase::$pluginId	protected	property	The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR		constant	A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId	public	function	Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId	public	function	Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition	3
PluginBase::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable	public	function	Determines if the plugin is configurable.
PluginBase::__construct	public	function	Constructs a \Drupal\Component\Plugin\PluginBase object.	92
RenderElement::preRenderAjaxForm	public static	function	Adds Ajax information about an element to communicate with JavaScript.
RenderElement::preRenderGroup	public static	function	Adds members of this group as actual elements for rendering.
RenderElement::processAjaxForm	public static	function	Form element processing handler for the #ajax form property.	1
RenderElement::processGroup	public static	function	Arranges elements into groups.
RenderElement::setAttributes	public static	function	Sets a form element's class attribute. Overrides ElementInterface::setAttributes
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	1
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.