Chapter 1. An introduction to OpenAPI Specification

In Red Hat 3scale API Management, the OpenAPI Specification (OAS) helps you to optimally manage OpenAPI documents. The OpenAPI Specification (OAS) provides you with the tools to update an existing service or create a new one.

The following are special considerations about OAS in 3scale:

Prerequisites

  • An OpenAPI document that defines your API.
  • A 3scale 2-saas instance tenant’s credentials (token or provider_key).

With OAS, the following features are available in 3scale:

Note

When you import an OpenAPI document, you create or update ActiveDocs. See How to write an OpenAPI document for use as a 3scale specification.

  • Ability to pass the 3scale service system_name as an optional parameter that defaults to info.title field from OAS.

  • Methods are created for each operation defined in the OpenAPI specification.

    • Method names are taken from the operation.operationId field.

  • All existing mapping rules get deleted before importing a new API definition.

    • Methods will be not deleted if they exist before running the command.
  • Mapping rules get created for each operation defined in the OpenAPI specification.

  • One of the following channels provides the OpenAPI definition resource:

    • Filename in the available path
    • URL format - toolbox will try to download from given address.
    • Read from stdin standard input stream.

1.1. Command line options for importing OpenAPI documents in 3scale

The 3scale command line interface (CLI) provides several options for importing OpenAPI documents that define APIs that you want to manage in 3scale. The following is the help information for the openapi option: 

NAME
    openapi - Import API definition in OpenAPI specification

USAGE
    3scale import openapi [opts] -d <dst> <spec>

DESCRIPTION
    Using an API definition format like OpenAPI, import to your 3scale API

OPTIONS
       -d --destination=<value>                   3scale target instance.
                                                  Format: "http[s]://<authentication>@3scale_domain"

 -t --target_system_name=<value>            Target system name

OPTIONS FOR IMPORT
    -c --config-file=<value>                      3scale toolbox
                                                  configuration file
                                                  (default:
                                                  $HOME/.3scalerc.yaml)
    -h --help                                     show help for this command
    -k --insecure                                 Proceed and operate even
                                                  for server connections
                                                  otherwise considered
                                                  insecure
    -v --version                                  Prints the version of this
                                                  command

1.2. Different sources to import API specifications

There are different sources available to you as a 3scale administrator for importing API specifications. These are outlined in the following table, which shows the usage options for detecting OpenAPI definitions from the filename path, the URL, and stdin.

Table 1.1. Detecting OpenAPI definitions

DescriptionFormatsCommand line usage

Detecting OpenAPI definition from the filename path. The format is automatically detected from filename extension.

json and yaml 

$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]

Detecting OpenAPI definition from a URL. The format is automatically detected from URL’s path extension.

json and yaml 

$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]

Detecting OpenAPI definition from stdin. The command line parameter for the OpenAPI resource is -. The format is automatically detected internally with parsers.

json and yaml 

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -