Though OpenAPI Specification (OAS) fits many use cases, specialized tweaks will be necessary in some cases. Extensibility refers to this customization. Developers may add data to key points within the specification to better accommodate external services or their own. This flexibility is key to unleashing OAS’ fullest potential. For example, you might want to add pagination to your APIs with Boto. Or, perhaps you want to utilize templates by extending Codegen. These additions help describe supplemental functionality.

OAS 3.0.3 requires that extension declarations begin with the -x field name prefix. Schema extensions can have any valid JSON format value, according to Swagger. Potential values are as follows:

• null
• Primitives
• Arrays
• Objects

An example of an OpenAPI property file extension. Image courtesy of API Handyman.

There are a variety of tools available to help with extensions. While tooling doesn’t accept EVERY extension out there, internal or open-source tools are also extensible for bolstered support. We’ve rounded up some useful options that’ll help put the finishing touches on your APIs:

LoopBack 4 OpenAPI Specification Enhancer

LoopBack is an open-source framework written in Node.js, originally developed for end-to-end REST APIs. The solution is low-code and asks less of developers than other alternatives. However, LoopBack 4 also includes a baked-in OpenAPI Specification Enhancer. This tool was built under the premise that applications should receive OAS contributions outside of their controllers and member metadata.

Your boilerplate coding will depend on what OAS data you’re editing via LoopBack. For example, editing the info field requires the InfoSpecEnhancer, which taps into LoopBack’s core OASEnhancer class:

Default code required to edit OAS info via LoopBack. Image courtesy of LoopBack.

LoopBack’s implementation also relies on modifySpec(), which tells the Enhancer what to edit within your existing OAS. You may merge, delete, or perform other operations that alter specification data. This works at varying degrees. While more intricate spec merging may occur, you can also perform basic merging to combine two JSON objects.

You can perform most operations in LoopBack 4 using under ten lines of code; its simple syntax saves development time. The program also does some heavy lifting automatically when you use its Extension Point — APIs can apply one Enhancer or every Enhancer simultaneously. While Registered Enhancers are applied using a common starting point, LoopBack warns that future applications will require custom sequences to work properly.

There aren’t too many moving parts to LoopBack 4’s OpenAPI Specification Enhancer, making it a superb option for developers needing a simple (yet powerful) tool. Note that features from LoopBack 3 are still under development for LoopBack 4, and not all are guaranteed to carry over. This may impact how OAS Enhancer functions down the road.

FastAPI

On the surface, FastAPI’s processes seem comparable to LoopBack’s in terms of simplicity. However, FastAPI warns users that extending OAS is “rather advanced.” Those who aren’t overly familiar with OAS schema manipulation or interpretation might not feel at home with FastAPI. Thankfully, the documentation is quite detailed and capable of leading you down the proper path. FastAPI conversely uses Python 3.6 compared to Node.js:

Generating a default FastAPI app prior to extension is fairly simple. Image courtesy of FastAPI.

OAS extensibility is a four-step process with FastAPI:

• Write a standard application using FastAPI
• Generate an OpenAPI schema using a utility function; this requires a title, version, description, and routes specification using a get request
• Modify the OpenAPI schema info object using extension notation, or -x
• Cache your generated schema if desired to enhance client-side performance and cut down on requests
• Override your existing openapi() method and replace it with a new function
• Confirm your changes within the browser using FastAPI’s IP address

FastAPI returns JSON responses via path operations. Your schemas don’t have to have contents for FastAPI to work; in fact, schema checking is a crucial precursor to data augmentation. Thankfully, FastAPI’s schema-generation process is quite efficient.

AWS API Gateway

Amazon API Gateway was created to help developers build, deploy, manage, monitor, and secure their APIs. Developers favor AWS for its REST API support and the wider ecosystem these APIs can take advantage of. How APIs connect to these backend systems is of particular interest to developers, and thus deeper configurations are sometimes necessary for your APIs.

AWS API Gateway lets you import Swagger and OpenAPI files. The Gateway also features a library of nearly 30 OAS extensions to manipulate objects, policies, properties, and fetch versions. Here’s the x-amazon-apigateway-any-method extension in action:

Using a Lambda function to integrate the ANY method with proxy resources. Image courtesy of API Handyman.

Note that the library is only applicable for API Gateway users. While this vast array of options may seem overwhelming, Amazon provides detailed documentation for each extension. Amazon also lets you see how API Gateway extensions are used within your applications — all you have to do is create a REST API and export it to an OpenAPI definition file. This is done via a simple GET request. For detailed next steps, follow along on Amazon’s guide here.

Amazon has built plenty of trust with developers over the years. The API Gateway, provided it suits your needs, is a safe option for sound OAS extensibility.

Remember Your use Cases

While choosing an OAS extension tool is often a matter of preference and your given objective, your end goals should determine which vendor you choose. You may want to configure API Gateway. You might also want to generate server or client code—or generate SDKs automatically. OAS extensions may also help with developer portal navigation. These priorities are paramount.

Backed by the tech world’s largest players, The OpenAPI Specification isn’t going anywhere soon. Nor are REST APIs. If you’re developing an OAS-centric API, these extensions are worth a look.