Revelio adapter for Open API specification
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Adapter to publish Open API specification files to a Revelio site.

Command line parameters

revelio-openapi <path_to_configuration_file> <revelio_url> [configuration_name] [options]

  • path_to_configuration_file - File path to your configuration file
  • revelio_url - URL of your Revelio installation
  • configuration_name (optional) - Name of the configuration to use
  • options
  • --publicKey <publicKey> - Public API key. Only necessary if your Revelio server requires API key authentication
  • --secretKey <secretKey> - Secret API key. Only necessary if your Revelio server requires API key authentication

Configuration file

In order to publish documentation to Revelio, you need to create a Revelio configuration file. This contains information about how to read documentation from your code and how it should be shown in Revelio.

Basic file

    "url": "",
    "target": "./myOpenApiSpec.yml",
    "path": "Sample Group/My API/QA/v1.2.3"

Multiple configurations

     "target": "./myOpenApiSpec.yml",
     "configurations": {
         "DEV": {
            "url": "",
            "path": "Sample Group/My API/DEV/v1.2.3"
         "QA": {
            "url": "",
            "path": "Sample Group/My API/QA/v1.2.3"
         "PROD": {
            "url": "",
            "path": "Sample Group/My API/PROD/v1.2.3"

Endpoint names

Revelio will attempt to use the optional operationId field for the endpoint name. If it you prefer to use a different name, you can specify it with the x-name extension. If neither field is provided, Revelio will generate a name based off the path and method. For example, GET /person/{personId} would have the name "Get Person". In most cases this is acceptable, but for endpoints like GET /person/byName it breaks down.

Additional attributes


You can add examples to parameters and properties by using the x-examples extension.

  - in: query
    name: firstName
    type: string
      - Mark
      - Bob
      - Lucius

Revelio will use the example field for simple types

  type: string
  example: doggie
# Adds "doggie" as an example for "name"

It will also use the example field for complex types

type: object
    type: integer
    format: int64
    type: string
  name: Puma
  id: 1

# Adds "Puma" as an example for "name", and "1" as an example for "id"

All of these approaches will be combined into a single list of examples per property


Any extension items that aren't already used for other purposes (e.g. x-examples and x-name) will be added as metadata for endpoints, parameters, and properties. See examples/withMetadata.yml for reference.

Open API Specification in Revelio

Please note that not all components of the specification are included in Revelio. We've aimed to include the pieces that fit the existing Revelio product. Let us know if you would like additional support added.