Swagger macro for displaying OpenAPI specifications.

Description

Swagger macro that allows to display OpenAPI specifications directly in your wiki.

Usage

WYSIWYG Editor

You can insert this macro from the WYSIWYG Editor. Look for the 'Swagger' in the list of macros.

Wiki Macro

{{swagger}}{{/swagger}}

Parameters

Name	Description
Show model as	Example JSON (example), JSON schema (model)
Display Operation ID	Show the ID of operations
Show request duration	Show the duration of 'Try it out' requests
Filter	Show only this tag
Limit number of tags displayed	Show at most this many tags
Methods sorter	Definition order (default), path (alpha), HTTP method (method)
Password	Password used for identification BitBucket.
Cors Proxy	Move the request to retrieve the OpenAPI specification from frontend to the backend to avoid CORS issues.
Show common extensions	Show extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters
Show vendor extensions	Show x- fields and values for Operations/Parameters/Schema
Supported submit methods	List the operations allowed in 'Try it out', separated by commas: get, post, put, delete, head, options, patch, trace. To disable 'Try it out' completely, enter none
Tags Sorter	Definition order (default), name (alpha)
Access token	Optional access token for the URL
URL	Use the JSON API definition at this location
Username	Username used for identification BitBucket.
Online API validator	Validator used to validate the API definition. To disable validation, leave it blank

Example:

{{swagger displayOperationId="false" proxy="false" showCommonExtensions="false" displayRequestDuration="false" showExtensions="false"}}
openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
{{/swagger}}

 

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Versions

Dependencies

Dependencies for this extension (org.xwiki.contrib.swagger:swagger-macro 1.0.1):

• org.webjars:swagger-ui 5.18.2
• org.webjars.npm:js-yaml 4.1.0
• org.xwiki.contrib.swagger:swagger-api 1.0.1