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:
- You can also import an OpenAPI specification (OpenAPI document) with the 3scale toolbox. See Importing OpenAPI definitions.
- Regarding OAS 3.0, 3scale 2.8 introduces changes. For more details, refer to Section 2.1, “OpenAPI Specification 3.0 usage with 3scale”.
Prerequisites
- An OpenAPI document that defines your API.
-
A 3scale 2.13 instance tenant’s credentials (
tokenorprovider_key).
With OAS, the following features are available in 3scale:
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_nameas 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.operationIdfield.
-
Method names are taken from the
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
command1.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.
| Description | Formats | Command 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 | json and yaml |
$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> - |
