Extension:Swiki

Category:Extensions without an imageCategory:MIT licensed extensions
MediaWiki extensions manual
Swiki
Release status: stableCategory:Stable extensions
Implementation Tag Category:Tag extensions
Description Embed Swagger UI to render OpenAPI and Swagger specifications on MediaWiki pages.
Author(s) Vuhuy (Shibe90talk)
Latest version 1.1.0
Compatibility policy Snapshots releases along with MediaWiki. Master is not backward compatible.Category:Extensions with release branches compatibility policy
Database changes No
License MIT License
Download

GitHub:

Note:
No localisation updates are
provided by translatewiki.net .

Category:Extensions in GitHub version control
README
Parameters
  • $wgSwikiForceColorScheme
  • $wgSwikiEnableSwaggerDocHook
  • $wgSwikiValidatorUrl
Tags
<swiki>, <SwaggerDoc>
Hooks used
Translate the Swiki extension if it is available at translatewiki.net
Category:All extensionsCategory:Extensions not in ExtensionJson

Swiki is a MediaWiki extension that allows you to seamlessly embed Swagger UI directly into your wiki pages using a simple <swiki> tag or through the VisualEditor. It includes a recent build of Swagger UI, providing full support for displaying your API documentation.

You can load OpenAPI or Swagger specifications in several ways: by embedding inline JSON, uploading a specification, referencing dedicated wiki pages that contain the specification, or linking to an external specification URL.

Swiki also includes Swagger Dark Theme, which is nicely integrated with MediaWiki skins that support dark mode, such as Vector-2022 and Minerva. Additionally, it can parse tags from third-party extensions like SwaggerDoc.

Head over to the GitHub project page for screenshots.

Installation

Developers can clone the extension into your MediaWiki extensions directory:

cd extensions/
git clone https://github.com/vuhuy/Swiki

Target a release branch instead when installing on production, e.g.:

git clone --branch REL1_43 https://github.com/vuhuy/Swiki

Then enable it by adding the following line to your LocalSettings.php:

wfLoadExtension( 'Swiki' );

Optional configuration variables:

  • $wgSwikiForceColorScheme: Forces a specific color scheme in Swagger UI. Accepted values are auto, light, or dark. Default: auto.
  • $wgSwikiEnableSwaggerDocHook: Enables parsing of SwaggerDoc tags when set to true. Default: false.
  • $wgSwikiValidatorUrl: Specifies a Swagger validator for displaying a validator badge, e.g., https://validator.swagger.io/validator. Default: null.

To allow users to upload OpenAPI/Swagger specifications, ensure that file uploads are properly configured and that .json is an allowed file extension:

$wgFileExtensions[] = 'json';

Usage

In order to use Swagger UI, provide your specification in JSON format or reference it via a link:

  • A relative direct link to a JSON file upload, e.g. /images/a/bc/swagger-petstore3.json. File uploads must be enabled and configured. Uploads can be done via Special:Upload.
  • A relative raw link to a wiki page that contains only the JSON specification, e.g., /wiki/Swagger_Petstore_3.json?action=raw. A raw link consists of the relative path to the page with the ?action=raw query appended. Optionally, you can set the page’s content model to JSON via the Special:ChangeContentModel page (requires the editcontentmodel permission).
  • An absolute external link to a specification, e.g. https://petstore3.swagger.io/api/v3/openapi.json. Must start with https:// or http://.

Visual editing

Insert a Swagger UI tag using the Insert menu in VisualEditor. Existing tags can be edited through their context menu. The Swagger UI dialog offers the following options:

  • OpenAPI/Swagger specification (JSON format): Inline a JSON specification directly into the page. YAML is not supported. This will override the Link and Links fields when used.
  • Link: Load a specification from a relative or absolute URL.
  • Links: Load multiple specifications from URLs. Each entry must follow the format url-to-spec|unique page name, separated by yet another | character. If the URL contains a pipe, encode it as %7C. This option overrides the Link field and always uses the standalone preset.
  • Render with standalone preset: Renders Swagger UI with a top bar (intended for standalone pages) that includes the URL or specification selector when multiple specifications are used.

Source editing

Use the <swiki> tag to render Swagger UI. Specifications and options can be provided in several ways:

  • As content: Inline the specification. Must be in JSON format, YAML is not supported. This will ignore the url and urls fields when used.
    <swiki>
{
  "openapi": "3.0.4",
  "info": {
    "title": "Swagger Petstore - OpenAPI 3.0",
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.",
    "termsOfService": "https://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.12"
  },
  [...]
}
</swiki>
  • URL attribute: Set the url attribute to render a single specification.
    <swiki url="/images/a/bc/swagger-petstore3.json" />
  • URLs attribute: Set the urls attribute to render multiple specifications. Entries must be formatted as url-to-spec|unique page name, separated by more pipes (|). Encode any pipe characters within URLs as %7C. This attribute overrides the url attribute and always uses the standalone preset.
    <swiki urls="/wiki/Swagger_Petstore_2.json?action=raw|Swagger Petstore 2|/wiki/Swagger_Petstore_3.json?action=raw|Swagger Petstore 3" />
  • Standalone attribute: When the standalone attribute is set, Swagger UI will render with a top bar.
    <swiki url="/wiki/Swagger_Petstore_3.json?action=raw" standalone />

Customization

The container in which Swagger UI is rendered can be styled using CSS via the MediaWiki:Common.css page. Only the outer container can be styled using this method. Swagger UI itself is rendered inside a shadow DOM, which isolates it from the rest of the wiki styles

.mw-ext-swiki-container
{
    /* Override container styles here. */
}

Credits

Category:All extensions Category:Extensions in GitHub version control Category:Extensions not in ExtensionJson Category:Extensions with release branches compatibility policy Category:Extensions without an image Category:MIT licensed extensions Category:ParserFirstCallInit extensions Category:Stable extensions Category:Tag extensions