Open API Specification 3.x Support

Information about the platform's support of Open API Specification 3.x (OAS 3.0 and 3.1) for API definitions.

Table of Contents

Working with OpenAPI 3.x:

• Open API 3.x support: Overview
• Difference between OpenAPI Specification 3.0 and 3.1
• How do I design an API from scratch in OAS 3.x?
• How do I edit an API design in OAS 3.x?
• Using the JSON Text Editor
• Displaying multiple examples in your OAS 3.x API documentation
• Open API specification using discriminator property
• Migrating from OpenAPI 3.0 to 3.1

JSON Schema Editor:

• Overview
• Adding and editing model objects in OAS 3.0
• How do I access the JSON Schema Editor?
• Using the JSON Schema Editor
• What validations can I add to model object properties in the JSON Schema Editor?
• How do I define a $ref reference to another model in the JSON Schema Editor?

Generated API Documentation for OAS 3.x:

• Viewing documentation for the same API in different formats

Working with OpenAPI 3.x:

Open API 3.0 support: Overview

The Akana API Platform supports OpenAPI version 3.0 for creating and updating API definitions.

You can define an OAS 3.0 document by:

• Uploading an existing OAS 3.0 API description document in JSON format.
• Designing from scratch: see How do I design an API from scratch in OAS 3.x?

Once you have the basic API definition in place, you can edit it in any of these ways:

• By uploading a new API description document.
• By editing in the API Designer user interface. See To edit an OAS 3.x API definition in the API Designer.
• By editing the Swagger definition in the Community Manager developer portal.

Some of the features of OAS 3.0 that are improvements from Swagger 2.0:

• The ability to define a response for each HTTP code/media type combination. For example, you can define an HTTP 200 (successful response) message for each Accept media type.
• Support includes an OAS Schema Form Editor, which is a graphical and text editor for authoring and editing Open API Specification v3 documents. The editor supports syntax and semantic validation on save or switch between text and graphical view, as well as code completion and syntax highlighting. The API Designer also supports dynamic switching between OAS 3.0 and other formats.

Open API 3.1 support: Overview

Valid in Version: 2024.1.0 and later

The Akana API Platform supports the creation and updating the API definitions using OpenAPI version 3.1. Limited support of the OpenAPI Specification 3.1 is provided as listed below:

• Creating and updating REST APIs using OAS 3.1 format.
• Downloading the OAS 3.1 API specification using an API.
• Validating the request payload for APIs using the HTTP Message Validation policy.
• Viewing the OAS 3.1 documentation with partial support for OAS 3.1 constructs.
• JSON Schema 2020-12 compatibility.
  • JSON schema type 'null'.
  • Discriminator property for oneOf and anyOf keywords.
• Response header validation.

Difference between OpenAPI Specification 3.0 and 3.1

The Akana API Platform supports OAS 3.0 and OAS 3.1 across all API lifecycle stages, including design, publishing, and deployment. Below is a table that details the current support coverage.

Feature	OAS 3.0	OAS 3.1	Additional information
Add or update an API from an API description document	Yes	Yes
Add or update an API using an API designer	Partial	Partial	Some constructs such as the discriminator, are supported using the swagger tab.
Publish generated API documentation	Yes	Yes	For more information, see API Documentation Maintenance.
Publish authored API documentation	Yes	Yes	For more information, see API Documentation Maintenance.
Download API documentation	Yes	Partial	The Community Manager developer portal user interface does not support downloading the API definition for OAS 3.1. You can download the API definition using the Get API Document.
Download Authored API documentation	Yes	Yes
Implement and Deploy API	Yes	Yes
Convert specifications	Yes	Partial	Some of the constructs cannot be converted to swagger 2.0.
Test client	Yes	Yes
Inline test client	Yes	Partial

How do I design an API from scratch in OAS 3.x?

Video content: Learn how to use Akana to easily create an API from scratch or from a file import (OAS3/Swagger/RAML/WSDL/WADL/GraphQL).

Follow the instructions for adding an API for OAS 3.0 and 3.1, providing the API name and clicking Save. For full instructions, see How do I add an API?

To design an OAS 3.x API from scratch

1. Log in to the Akana API Platform.
2. Go to APIs > Add API. The Add API page opens.
3. Optional: click the advanced options icon on the right, and choose a different implementation pattern. Proxy is the default, but you can also choose Orchestration or Physical Service. See What is the API pattern and which pattern should I choose?
4. Specify a name for the API, and click Save. The API Designer opens in the initial view so that you can start defining your API in the visual designer, as shown below.

   

5. Resources: Define resources as needed. For detailed instructions, see Resources (Operations).
6. Models: Define models as needed. For detailed instructions, see Model Objects.
7. Tags: Define tags as needed. For detailed instructions, see Tags.
8. Settings: In the Settings section, define default media types as needed. For detailed instructions, see What are default media types and how do I set them up?
9. When done, click Save.

Note: You can also define the API by working directly with the OAS 3.0 JSON definition rather than the visual editor. Just click the JSON tab at the top of the page. For more information, see Using the JSON Text Editor.

How do I edit an API design in OAS 3.x?

By default, the JSON Schema Editor converts any Swagger API description document to OAS 3.x. However, you can also choose Swagger 2.0.

To edit an OAS 3.0 API definition in the API Designer

1. Go to APIs > My APIs > choose API > Details.
2. In the Design section, on the right, click Edit. The JSON Schema Editor opens. By default, the API description is displayed as an OAS 3.0 document.

   Note: You can also click the drop-down, as shown below, and choose Swagger 2.0.

   

3. Edit any components of the API design. For details, refer to the linked procedure below. You can add, edit, or delete:
   • Resources: See Resources (Operations).
   • Models: See Model Objects.
   • Tags: See Tags.
   • Settings: set up default media types. See What are default media types and how do I set them up?
4. You can also directly edit the OAS 3.0 API description document: click the JSON tab to access the API description in the JSON Text Editor. See Using the JSON Text Editor.
5. Click Save.

Note: You can also define the API by working directly with the OAS 3.0 JSON definition rather than the visual editor. Just click the JSON tab at the top of the page. For more information, see Using the JSON Text Editor.

To edit an API created using OAS 3.1 specification

1. Go to APIs > My APIs > choose API > Details.
2. In the Design section, on the right, click Edit. The JSON Schema Editor opens. Click Import OAS 3.1.

   

3. Follow the steps 3-5 from OAS 3.0 API definition.

Using the JSON Text Editor

If you prefer to edit the plain JSON for your API definition rather than working in the API Designer, click the JSON tab to edit the OpenAPI 3.0 or 3.1 swagger JSON file. The OpenAPI 3.0 or 3.1 swagger JSON file is displayed.

The following example shows a sample OAS 3.0 file to edit using the JSON text editor.

Sample OAS 3.0 file for a new API with no API definition

If you choose to provide a name, and then design from scratch, the platform creates a placeholder OAS 3.0 Swagger document using the name you provided, as shown below.

Sample OAS 3.0 file when API definition document was uploaded

Editing in the JSON Text Editor

In the JSON Text Editor you can directly modify your OAS 3.0 API definition. The Editor has built-in features to help you design your API, such as:

• Syntax highlighting, as shown above.
• Code hinting as you type. An example is shown below.

  

• Search for model objects includes typeahead search in popup dialog for search; the results are a drop-down list with hover for description.
• Contextual help. Type CTRL+Spacebar to access the contextual help, as shown in the example below.

  

• Syntax and semantic validation when you switch between text and graphical view.
• Validation on save. You cannot save the file unless the JSON is valid and conforms to the OpenAPI 3.0 standard.

Displaying multiple examples in your OAS 3.x API documentation

Valid in Version: 2020.2.8, 2022.1.0

OAS 3.x supports displaying multiple examples in your OAS 3.x API documentation, for parameters, request bodies, and responses.

In the OAS 3.x file, you can use the examples attribute to include multiple example attributes.

In the Community Manager developer portal user interface, when users view the documentation, a drop-down allows the user to select from available examples. In the example below, there are two choices.

For more information about including multiple examples in your OAS 3.x API documentation, refer to https://swagger.io/docs/specification/adding-examples/.

Note: Where a feature is supported in one or more API documentation formats but not others, converting to other formats is not supported. For example, conversion from OAS 3.0 to Swagger 2.0 might not be 100% because of differences in features supported by both specifications.

Open API specification using discriminator property

The Open API discriminator is a specific object in a schema that supports a set of mapping values to help determine which schema to map based on the discriminator property's value in the payload.

For information on the discriminator object fields, see the following table.

Field name	Type	Description
propertyName	string	Required. The name of the property that will hold the discriminator value.
mapping	Map[string, string]	Optional. An object to hold mappings between payload values and schema names or references.

The discriminator object must be used in combination with anyOf, oneOf, or allOf to validate a request body based on the OpenAPI specification. You can use the following keywords with a discriminator and/or mapping field to validate a value against the schema.

• oneOf: validates the value against exactly one of the subschemas
• allOf: validates the value against all the subschemas
• anyOf: validates the value against any (one or more) of the subschemas

The following structure shows the discriminator object with a property name petType and a discriminator keyword oneOf to validate the schema. When using the discriminator keyword only one subschema in oneOf will be used determined by the value of the discriminator property.

PetRequestTypeOneOf
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: petType
    mapping:
     Cat: '#/components/schemas/Cat'
     Dog: '#/components/schemas/Dog' 

In the example below, there are two subschemas - a Dog and a Cat. In the definition of the subschemas, you can then specify the discriminator value either as an enum or a constant.

components:
  schemas:
   Pet:
    type: object
    required:
    - petType
    properties:
      petType:
       type: string
    discriminator:
      propertyName: petType
      mapping:
       dog: Dog
  Cat:
   oneOf:
   - $ref: '#/components/schemas/Pet'
   - type: object
   # all other properties specific to a `Cat`
   properties:
      name:
        type: string
  Dog:
   oneOf:
   - $ref: '#/components/schemas/Pet'
   - type: object
   # all other properties specific to a `Dog`
   properties:
     bark:
       type: string

The following payload allows to match one of the schemas (the Dog schema).

{
  "petType": "dog",
  "bark": "soft"
} 

The oneOf discriminator clarifies the potential matching types by using the value of a single property to discover the correct schema to match. The dog has a discriminator value of dog based on the mapping values of model Pet. The model Cat has a discriminator value of Cat since it has no mapping information available and therefore uses the schema's name as its discriminator value. The discriminator value of a dog will be mapped to the schema, rather than a default value of the Dog. If the discriminator value does not match the mapping, no schema can be determined and validation must fail.

Migrating from OpenAPI 3.0 to 3.1

The OpenAPI version 3.1 has introduced new functionality and enhancements. To upgrade from OpenAPI 3.0 to 3.1, refer to Migrating from OpenAPI 3.0 to 3.1.0.

JSON Schema Editor:

To edit schema definitions, use the JSON text editor tab to modify the JSON for your API definition rather than using the JSON schema editor. The support for OAS 3.x constructs is lacking in the schema editor and does not support OAS 3.1 for creating and editing JSON schema definitions using the JSON schema editor.

Overview

The JSON Schema Editor is a graphical user interface for creating and editing JSON schema definitions, using JSON Schema Draft 4. It includes such features as:

• Code completion
• Syntax highlighting
• Syntax and semantic validation when you save or switch between text and graphical view

Adding and editing model objects in OAS 3.0

You can add and edit model objects in the API Design view, Models section.

With OAS 3.0, the default view, the tabs are:

• Editor (the default): the JSON Schema Editor.
• JSON: when you click the JSON tab you can directly edit the OAS 3.0 Swagger document. For details, see Using the JSON Text Editor.

How do I access the JSON Schema Editor?

The JSON Schema Editor is available in two places in the Community Manager developer portal:

• For the API Admin: in the API Designer.

  Go to APIs > My APIs > choose API > Details. In the Design section, click Edit. In the Models section, click Add, or select an existing model and click Edit.

• For the Business Admin: in the context of a specific business model.

  Go to More > Organizations > choose organization > Models > Add. Provide name and any other basic details and click Save to access the Edit Schema page. The JSON Schema Editor is the default view.

Using the JSON Schema Editor

The initial view in the JSON Schema Editor, after defining an API, is shown below.

With OAS 3.0, the default view, the tabs are:

• Editor (the default): the JSON Schema Editor.
• JSON: when you click the JSON tab you can directly edit the OAS 3.0 Swagger document. For details, see Using the JSON Text Editor.

Note: You can also define the API by working directly with the OAS 3.0 JSON definition rather than the visual editor. Just click the JSON tab at the top of the page. For more information, see Using the JSON Text Editor.

To author in the JSON Schema Editor

1. Go to the Design page for your API and click Add Model. The initial view of the JSON Schema Editor, for a new model, is shown below.

   

2. Enter the name for the model object.
3. Define one or more properties. For each property:
   • Click the + sign, and then click object and specify the object type from the list below (your installation might include additional custom object definitions).

     

     Default object types available: String, Number, Integer, Boolean, Object, Array, $ref, oneOf, anyOf, allOf, patternProperty. For Array, you must specify the data type for the array (String, Number, Integer, Boolean, or $ref). For $ref, you must specify the referenced object. For patternProperty, you must specify the pattern (regular expression) that the value must match, and the object type.

   • Specify the ID (property name) and click Finish.
   • Optional: on the right, click the Validations link to specify validations. For example, if you choose Integer, you can specify int32 or int64. When done, click Finish on the Validations overlay. For more information about validations that you can add, see What validations can I add to model object properties in the JSON Schema Editor?
   • Optional: if the property is required, check the required box, as shown below.

     

4. On the Add Model dialog, click Finish to save the new model. You are returned to the API Designer.

   Note: Changes are not permanently saved until you click Save on the API Designer page. Remember to save before exiting.

   You can also switch between tabs. When you switch, the platform automatically validates the API description, and provides messaging if there are validation errors.

What validations can I add to model object properties in the JSON Schema Editor?

When you're adding or modifying elements, in the JSON API description, you can specify validations that must be applied to various elements.

The specific validations available vary according to the type of element.

Some examples and their definitions are shown below, in these sections:

Common Validations

Dependencies

If validation is required against other properties, specify the dependencies. An example from the Swagger Petstore API: id, quantity, shipDate, status, complete.

String Validations

Enum

Enter the items for the enumerated list, with comma separators. For example: placed,approved,delivered.

Format

A valid sub-format for the data type. For Integer, options are: int32 or int64.

Minimum Length

Minimum allowable length for the string.

Maximum Length

Maximum allowable length for the string.

Pattern (regexp)

A regular expression pattern that the string must match.

Number Validations

See Integer Validations below.

Integer Validations

Enum

Enter the items for the enumerated list, with comma separators. For example: placed,approved,delivered.

Format

A valid sub-format for the data type. For Integer, options are: int32 or int64.

Multiple Of

An integer value that the property value must be a multiple of.

Minimum

Minimum allowable integer value for the property.

Maximum

Maximum allowable integer value for the property.

Boolean Validations

None except common validations (dependencies).

Object Validations

Minimum Number of Properties

Enter an integer value.

Maximum Number of Properties

Enter an integer value.

Additional Properties Allowed?

Specify Yes, No, or Specify Properties Allowed. If you choose to specify, an additional field appears, for Additional Property Types:

Array Validations

Arrays have these sets of validations:

• Common Validations
• Validations for the data type specified for the array
• Array Validations listed below

Additional Items Allowed?

Default is Yes. You can change to No, or click Specify Types Allowed and specify the data type for additional items allowed in the array.

Minimum Number of Items

The minimum allowable number of items for the array to be valid.

Maximum Number of Items

The maximum allowable number of items for the array to be valid.

Unique Items

Check the box to add validation that an item appears only once in the array.

$ref Validations

When you're defining a $ref property, you must specify the destination object that's being referenced.

There are no other validations for $ref properties.

oneOf Validations

When you choose an object type of oneOf, a sub-object is created. You can then go in there and specify what the property must be one of, as shown below.

There are no other validations for oneOf properties.

anyOf Validations

In the same way as oneOf shown above, when you choose an object type of anyOf, a sub-object is created. You can then go in there and specify what the property must be any of.

There are no other validations for anyOf properties.

allOf Validations

In the same way as oneOf shown above, when you choose an object type of allOf, a sub-object is created. You can then go in there and specify what the property must be all of.

There are no other validations for allOf properties.

Note:

When using the HTTP Message Validation policy and OpenAPI schemas "allOf", "anyOf", or "oneOf", take the following actions.

• The additionalProperties must be set to true for all the objects in the "allOf" schema.

• If the combining operation is "anyOf" or "oneOf" and its schema is a primitive with no properties, set additionalProperties to false.

• If the combining operation is "anyOf" or "oneOf" and its schema is an object with properties, set additionalProperties to true.

For more information, refer to additional properties.

patternProperty Validations

When you're defining a patternProperty property, you must specify the pattern (regular expression) that the value must match, and the object type. For example, if you specify a pattern of [0-9]{3}, the value must be three digits.

For validations available, refer to the validations for the object type you specify.

How do I define a $ref reference to another model in the JSON Schema Editor?

When defining your models, it's best to define the models that are referenced by others, before adding the $ref references to those models.

When you add a $ref, you'll need to specify which model is being referenced. The portal offers you a list of valid models to choose from, as shown in the example below. Because of this, you really need to define the referenced model first.

For basic instructions on defining a model, see Using the JSON Schema Editor.

Notes re the model object selection list

Two types of model objects might appear on the list:

• Models already defined in the context of the current API.
• Models defined for the business.

In the example above, the first model was defined in the context of the API and the other two are global model objects.

In addition, global model objects can have multiple versions. The version is included in the path so that it's clear what you're selecting.

Note: When you choose a global model object, it becomes local to the API. At that point, you can change it without affecting the global definition. Changes to the global model object do not filter down to your API, and additional versions do not apply to the API. If you want to update to a newer global model object, go into the API definition, as above, and choose the new model from the list.

Generated API Documentation for OAS 3.x:

Viewing documentation for the same API in different formats

When you define or upload your API, in Swagger 2.0 or OAS 3.x, API documentation is generated automatically from the API design.

You can control whether the API documentation is available in Swagger format (.swg file) or in OAS 3.x format (.oas file). So, for example, if could create an API by uploading an OAS 3.0 API description document, you might choose to make your API documentation available in Swagger 2.0 as well, for users who are not familiar with OAS 3.0.

Because there are differences in the properties that are supported in OAS 3.x versus Swagger 2.0, a specific property supported by only one version will only show up in that version of the API documentation.

For example, let's say you create your API by uploading an OAS 3.0 document, and the API includes the allOf property. You choose to make the API documentation available in Swagger 2.0 format as well as OAS 3.0 format. In this scenario, because allOf/oneOf/anyOf are only supported in OAS 3.0, the allOf property will not appear in the Swagger 2.0 generated API documentation. It will appear only in the OAS 3.0 version.

Related Topics