Chapter 5. How to write an OpenAPI document for use as a 3scale OpenAPI spec

ActiveDocs is an instance of OAS. With ActiveDocs, you do not have to run your own OAS server or deal with the user interface components of the interactive documentation. The interactive documentation is served and rendered from your 3scale Developer Portal.

3scale 2.8 introduced OAS 3.0 with limited support in ActiveDocs. This means that some features working with ActiveDocs, such as autocompletion, are not yet fully integrated, and consequently 3scale defaults to OAS 2.0 when creating new accounts. For more details about OAS 3.0 and ActiveDocs, refer to Section 2.1, “OpenAPI Specification 3.0 usage with 3scale”.

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

3scale extends OAS in several ways to accommodate certain features that are needed for Developer Portal interactive API documentation:

To read the specification from the original source, see the OpenAPI Specification.

On the OAS site, there are multiple examples of OpenAPI documents that define APIs. If you like to learn by example, you can follow the example of the Petstore API by the OAS API Team.

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

The Petstore API is integrated with 3scale, and for this reason you must add an additional parameter for authentication. For example, with the user key authentication method, an API consumer must put the user key parameter in the header of each request. For information about other authentication methods, see Authentication patterns.

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

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"

If you want your 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.

OAS relies on a resource declaration that maps to a hash encoded in JSON. Use the Petstore swagger.json file as an example and learn about each object.

Parameters that are not objects use primitive data types. In Swagger, primitive data types are based on the types supported by the JSON-Schema Draft 4. There is an additional primitive data type file but 3scale uses it only if the API endpoint has CORS enabled. With CORS enabled, the upload does not go through the api-docs gateway, where it would be rejected.

Currently OAS supports the following dataTypes:

The following tools are useful for designing and editing the OpenAPI specification that defines your API:

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

"parameters": [
  {
    "name": "user_key",
    "in": "query",
    "description": "Your API access key",
    "required": true,
    "schema": {
      "type": "string"
    },
    "x-data-threescale-name": "user_keys"
  }
]

For the parameters declared with x-data-threescale-name, when you log in to the Developer Portal you will see a drop-down list with the 5 latest keys, user key, App Id or App key, according to the value configured in the specification. So you can auto-fill the input without having to copy and paste the value: