Image source: Pixabay


The OpenAPI specification has grown popular in the past few years especially when it comes to documenting and describing APIs. This is fueled by the many benefits the specification offers to organizations.

Some of the notable benefits include the support the specification gets from different API management tools and the fact that organizations can generate specifications and documentation from the client side easily.

Instead of using XML elements in OpenAPI, developers are required to use JSON objects. This comes with a schema used for contents, order, and naming. The JSON file is used to describe all the parts of the API in a standard format.


What is OpenAPI Specification?

Formally known as the Swagger Specification, the OpenAPI specification can be described as an API description format used for REST APIs. With an OpenAPI file, organizations can describe their APIs. The description includes things such as;

  • All authentication methods used.
  • The output and input methods for all endpoints.
  • All the available methods such as POST and GET, and endpoints such as URLs.


Apart from using the specification to document their APIs, organizations can also use it to generate client code and the required documentation. The good news is that most API management tools come with support for OpenAPI specification. This not only makes it easy to create APIs but also to maintain them.

Some main components you will find with the OpenAPI specification include security, responses, parameters, and paths. Each of these components holds arrays and properties as JSON objects.

You will get descriptions, contact, license, document version, and all the information you need about the APIs in the info field. The server field, on the other hand, describes all the endpoints used in the API.

An API can be defined as a computing interface that allows applications to communicate and share information. Due to their growing popularity, cybersecurity has become one of the biggest concerns for organizations. Cybercriminals are targeting organizations through APIs to try and steal information and data that they access.

Here are a few important security facts you need to know about the OpenAPI specification;

Where Security is Defined in OpenAPI Specification

You can define security in three different places in the OpenAPI specification. These include;

Under #/security

This is the default place where security is supposed to be defined in the OpenAPI specification. It is also supposed to match with a named security scheme that can be or will be found under #/components/securitySchemes.

If by any chance you do not define security under #/security or it is found to be an empty object, then your API will not be secured by default. This is common with small APIs that come with few endpoints open to most users. However, they define security specific to certain operations.


Under #/components/securitySchemes

This is the default place for the definition of the security options you have for your API. Smaller APIs normally come with a single option. You can set anything you want as the key name. The name you set here will be used when being referenced from anywhere else in the specification.

Type is, however, a required parameter. It can be either oauth2, HTTP, apikey, or the new openIdConnect and mutualTLS. All the other parameters change depending on the type used.


Under Certain Operations

Finally, you can set your OpenAPI security under certain operations. Again, you will use one of oauth2, HTTP, apikey, or the new openIdConnect and mutualTLS. However, this is done under a certain operation that lies on a certain path.

If you do not have security defined under certain operations, then the top-level security defined under #/security will be used by the API. This is important for APIs with operations that need to use different security parameters.


OpenAPI 3.0 Security Features

OpenAPI 3.0 comes with a dedicated part of its document known as security schemes where you are supposed to declare all security definitions. The OpenAPI specification has standardized how all the parts of the document are supposed to be declared.

This ensures that you can reuse anything declared in the security schemes across different paths without any problems. Previously in OpenAPI 2.0, the shared components were left at the mercy of developers. In OpenAPI 3.0, all of them can now be found within the components key.

In addition, OpenAPI 3.0 comes with support for OpenID Connect. Organizations are also able to include different oAuth2 flows in their security definitions. This is one of the most popular functionalities today.


OpenAPI 2.0 Security Features

OpenAPI 2.0 specification comes with a section that is dedicated to the declaration of all security requirements and features used in your API. These security features can be used anywhere in the API operations and paths.

It also comes with support for a type of security definition known as basic. This is the previous plain HTTP format of authentication

Unfortunately, you will not find any other built-in security features with OpenAPI 2.0. You cannot even define your custom security definitions without having to use extensions provided by external vendors.

Even though this is enough for most API security requirements, it might not work well with some special cases. Understanding the security features in both OpenAPI 2.0 and 3.0 is vital in making sure that your APIs are secure.