Menu Close
Settings Close

Language and Page Formatting Options

Chapter 2. Create an OAS spec

This section will help you to create a OpenAPI Specification 2.0-compliant (OAS) specification for your RESTful API, which is required to power ActiveDocs on your Developer Portal. If you only would like to read the code, all the examples are on OAS Petstore example source code.

2.1. About OpenAPI Specification (OAS)

3scale ActiveDocs are based on the specification of RESTful web services called Swagger (from Wordnik). This example is based on the Extended OpenAPi SpecificationPetstore example and draws all the specification data from the OpenAPi Specification 2.0 specification document.

OAS is not only a specification. It also provides a full feature framework around it:

  1. Servers for the specification of the resources in multiple languages (NodeJS, Scala, and others).
  2. A set of HTML/CSS/Javascripts assets that take the specification file and generate the attractive UI.
  3. A OAS codegen project, which allows generation of client libraries automatically from a Swagger-compliant server. Support to create client-side libraries in a number of modern languages.

2.2. 3scale ActiveDocs and OAS

ActiveDocs is not a OAS replacement but an instantiation of it. With ActiveDocs, you don’t have to run your own OAS server or deal with the UI components of the interactive documentation. The interactive documentation is served and rendered from your 3scale Developer Portal.

The only thing you need to do is to build a Swagger-compliant specification of your API, add it on your Admin Portal, and the interactive documentation will be available. Your developers will be able to launch requests against your API through your Developer Portal.

If you already have a Swagger-compliant specification of your API, you can add it in your Developer Portal (see the tutorial on the ActiveDocs configuration).

3scale extended the OAS specification in several ways to accommodate certain features that were needed for our own interactive API documentation:

  • Auto-fill of API keys
  • OAS proxy to allow calls to non-CORS enabled APIs

2.3. Creating the specification of your API

We recommend that you first read the original specification from the original source: the OAS Specification.

On the OAS site there are multiple examples of specifications. If you like to learn by example, you can follow the example of the Petstore API by the OAS API Team.

2.3.1. Learning by example: the Petstore API

The Petstore API is an extremely simple API. It is meant as a learning tool, not for production.

The Petstore API is composed of 4 methods:

  • GET /api/pets - returns all pets from the system
  • POST /api/pets - creates a new pet in the store
  • GET /api/pets/{id} - returns a pet based on a single ID
  • DELETE /api/pets/{id} - deletes a single pet based on the ID

Because Petstore is integrated with 3scale API Management, you have to add an additional parameter for authentication – for example, the standard User Key authentication method (there are others) sent in the headers.

You need to add the parameters:

user_key: {user_key}

The user_key will be sent by the developers in their requests to your API. The developers will obtain those keys on your Developer Portal. On receiving the key, you must to perform the authorization check against 3scale using the Service Management API.

For your developers, the documentation of your API represented in cURL calls would look like this:

curl -X GET "" -H "user_key: {user_key}"
curl -X POST "" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "{id}" -H "user_key: {user_key}"
curl -X DELETE "{id}" -H "user_key: {user_key}"

However, if you want the documentation to look like the OAS Petstore Documentation, you must create a Swagger-compliant specification like the associated Petstore swagger.json file. You can use this specification out-of-the-box to test your ActiveDocs. But remember that this is not your API. You can learn more in the next section.

2.3.2. More on the OAS specification

The OAS specification relies on a resource declaration that maps to a hash encoded in JSON. Take the Petstore swagger.json file as an example and go step by step. OAS object

This is the root document object for the API specification. It lists all the highest level fields.


The host must be a domain and not an IP address. 3scale will proxy the requests made against your Developer Portal to your host and render the results. This requires your host and basePath endpoint to be whitelisted by us for security reasons. You can only declare a host that is your own. 3scale reserves the right to terminate your account if we detect that you’re proxying a domain that does not belong to you. This means that local host or any other wildcard domain will not work. Info object

The Info object provides the metadata about the API. This will be presented in the ActiveDocs page. Paths object

The paths object holds the relative paths to the individual endpoints. The path is appended to the basePath to construct the full URL. The paths may be empty, due to ACL constraints.

Parameters that are not objects use primitive data types. In Swagger, these are based on the types supported by the JSON-Schema Draft 4. There is an additional primitive data type "file" but it will work only if the API endpoint has CORS enabled (so the upload won’t go through api-docs gateway). Otherwise, it will get stuck on the gateway level.

Supported datatypes

Currently OAS supports the following dataTypes:

  • integer with possible formats: int32 and int64. Both formats are signed.
  • number with possible formats: float and double
  • string with possible formats (besides the unformatted version): byte, date, date-time, password
  • boolean

2.3.3. Useful tools

The JSON Editor Online is useful if you are very familiar with the JSON notation. It gives a pretty format to compact JSON, and it also provides a JSON object browser.

The OAS Editor is another useful tool. This enables you to create and edit your OAS API specification written in YAML in your browser and preview it in real time. You can also generate a valid JSON specification, which you can upload later in your 3scale Admin Portal. You can use the live demo version with limited functionality or deploy your own OAS Editor. Extension to the OAS specification: auto-fill of API keys

Auto-fill of API keys is a useful extension to the OAS specification in 3scale ActiveDocs. In the parameters, you can define the x-data-threescale-name field with the following values depending on your API authentication mode:

  • user_keys - returns the user keys for applications of the services that use API key authentication only.
  • app_ids - returns the IDs for applications of the services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).
  • app_keys - returns the keys for applications of services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).
  • client_ids - returns the client IDs for applications of the services that use OAuth/OpenID Connect authentication only.
  • client_sercrets - returns the client secrets for applications of the services that use OAuth/OpenID Connect authentication only.

API key authentication example

The following example shows using "x-data-threescale-name": "user_keys" for API key authentication only:

"parameters": [
    "name": "user_key",
    "description": "Your access API Key",
    "type": "string",
    "in": "query",
    "x-data-threescale-name": "user_keys",
    "required": true

App ID/App Key authentication example

For App ID/App Key authentication mode, specify "x-data-threescale-name": "app_ids" for the parameter that represents the application ID, and "x-data-threescale-name": "app_keys" for the parameter that represents the application key.

When you have declared your parameters, ActiveDocs will automatically prompt the ActiveDocs user to log in to the Developer Portal to get their keys as shown in the following screenshot:

Auto-fill when not logged-in

If the user is already logged in, ActiveDocs will show the latest five keys that could be relevant for them so that they can test right away without having to copy and paste their keys.

Auto-fill when logged-in

The x-data-threescale-name field is an extension to the OAS specification that will be ignored outside the domain of ActiveDocs.