Open API Specification 3.0 Support

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

Table of Contents

Working with OpenAPI 3.0:

• Open API 3.0 support: Overview
• How do I design an API from scratch in OAS 3.0?
• How do I edit an API design in OAS 3.0?
• Using the JSON Text Editor
• Displaying multiple examples in your OAS 3.0 API documentation

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.0:

• Viewing documentation for the same API in different formats

Working with OpenAPI 3.0:

Open API 3.0 support: Overview

The Akana API Platform supports OpenAPI version 3.0 (OAS 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.0?

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.0 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.

How do I design an API from scratch in OAS 3.0?

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, providing the API name and clicking Save. For full instructions, see How do I add an API?

To design an OAS 3.0 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.0?

By default, the JSON Schema Editor converts any Swagger API description document to OAS 3.0. 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. 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.

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. The OpenAPI 3.0 swagger JSON file is displayed, as shown in the examples below.

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.0 API documentation

Valid in Version: 2020.2.8, 2022.1.0

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

In the OAS 3.0 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.0 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.

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.0:

Viewing documentation for the same API in different formats

When you define or upload your API, in Swagger 2.0 or OAS 3.0, 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.0 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.0 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