Swagger UI

A plugin is a function that returns an object used to augment or modify Swagger UI's functionality. The returned object can contain state plugins (actions, reducers, selectors), components, wrappers for existing logic, and helper functions.

Important: Dependency Management Swagger UI does not have built-in dependency management for plugins. If your plugin depends on another, you must ensure the dependent plugin is loaded after the plugin it relies on.

Important: Semantic Versioning Swagger UI's internal APIs are not part of the public contract and may change without a major version update. If your plugin consumes or overrides internal core APIs, it is recommended to pin your dependency to a specific minor version using a tilde (e.g., "swagger-ui": "~3.11.0") in your package.json.

const MyPlugin = function(system) {
  return {
    // plugin implementation
  };
};

Swagger UI uses specific component names to map OpenAPI Specification schema information to input components. You can define custom input components by matching the following naming convention:

1. If format is defined: JsonSchema_${type}_${format}
2. Fallback (if format not defined or component missing): JsonSchema_${type}
3. Default: JsonSchema_string

Example: Implementing a Date-Picker To integrate a library like react-datepicker for format: date and format: date-time, you must provide components named JsonSchema_string_date and JsonSchema_string_date-time.

import React from "react";
import DatePicker from "react-datepicker";
import "react-datepicker/dist/react-datepicker.css";

const JsonSchema_string_date = (props) => {
  const dateNumber = Date.parse(props.value);
  const date = dateNumber ? new Date(dateNumber) : new Date();

  return (
    <DatePicker
      selected={date}
      onChange={d => props.onChange(d.toISOString().substring(0, 10))}
    />
  );
}

const JsonSchema_string_date_time = (props) => {
  const dateNumber = Date.parse(props.value);
  const date = dateNumber ? new Date(dateNumber) : new Date();

  return (
    <DatePicker
      selected={date}
      onChange={d => props.onChange(d.toISOString())}
      showTimeSelect
      timeFormat="p"
      dateFormat="Pp"
    />
  );
}

export const DateTimeSwaggerPlugin = {
  components: {
    JsonSchema_string_date: JsonSchema_string_date,
    "JsonSchema_string_date-time": JsonSchema_string_date_time
  }
};

Swagger-UI uses a plugin system to extend its core functionality. A plugin is a factory function that receives a toolbox argument and returns an object containing different types of extensions. These extensions are merged into a global system object and then bound to the application state.

Plugin Types

• statePlugins: Used to manage application state via namespaces. Each namespace can contain:
  • selectors: Functions used to query the state. They are passed a getState function to ensure they remain decoupled from specific state instances.
  • reducers: Functions that modify the state. They receive the current state (which is an Immutable object) and an action, returning a new state.
  • actions: Functions that trigger state changes.
    • Synchronous actions must return a plain object (e.g., { type: 'ACTION_NAME', payload: ... }) for the reducer to handle.
    • Asynchronous actions must return a function that receives the system as an argument, allowing it to call other actions.
  • wrapActions: A way to intercept and replace existing actions. This is useful for adding side effects (like logging) while still calling the original action.
• components: A map of names to React components.
• fn: A collection of common utility functions.

The toolbox Argument

The plugin factory function receives a toolbox object. This object provides access to the entire plugin system at the time the plugin is called and includes a reference to the Immutable library (e.g., toolbox.Im), so plugin authors do not need to bundle it themselves.

export function SomePlugin(toolbox) {
  return {
    statePlugins: { /* ... */ },
    components: { /* ... */ },
    fn: { /* ... */ }
  };
}

Error transformers allow you to intercept and modify error messages generated by Redux error actions before they are processed by the reducer. This is useful for making error messages more user-friendly or adjusting metadata like line numbers.

Data Contract

Input: The transform function receives an Immutable List of Immutable Maps representing the current errors.

Output: The function must return a List of Immutable Maps with the same structure.

Required Keys: To ensure compatibility with the UI, every error map returned by your transformer must contain the following keys:

• line
• level
• message
• source
• type

Deleting Errors

To completely remove an error from the state, return null in place of that error within the returned list. The system will automatically filter out null values before returning the final error array.

export function transform(errors) {
  return errors.map(err => {
    err.line += 10
    return err
  })
}