RepreZen and OpenAPI 3.0: Now is the Time

Miles Daffin
Posted by
Miles Daffin on Sep 12, 2018 08:44 AM
OAS3 Update Blog Image (shadow).png

A lot of API providers have been waiting to upgrade from OpenAPI 2.0 to 3.0 as their go-to API description language. Most have been looking for two things: (1) signs of broader adoption; and (2) more robust tool support.

Now, OpenAPI 3.0 has broken through on both fronts, and is moving forward fast. This is a great time to move to OAS3, and RepreZen offers a great set of new capabilities and resources to help you learn OpenAPI v3, upgrade your current Swagger specs, and start building APIs today.

Better API Descriptions

OpenAPI v2, formerly known as the Swagger 2.0 specification language, evolved hand-in-hand with the Swagger framework, and represented an opinionated perspective on REST API design. Starting with 3.0, the OpenAPI Initiative is reshaping the language to cover a broader set of use cases, implementations, and API design styles.

OAS3 is a more versatile language. You can design APIs with better modularity and reuse, and with more flexibility and detail in message schemas, parameters, security schemes, servers, and media types. And you can describe advanced API features like callbacks and links.

Forward-Looking API Providers Use OAS3

In recent months, we've seen new announcements of OpenAPI 3.0 support at an accelerating pace. Here are a few:

  • The Netherlands Government 
    external link icon
     
    has standardized on OpenAPI 3.0 for greater alignment and interoperability across national, provincial and municipal agencies.
  • eBay 
    external link icon
     now provides OpenAPI 3.0 descriptions for its Buy APIs and Commerce APIs in OAS3 format, for easier integration across multiple technology stacks.
  • The U.S. Department of Veterans Affairs 
    external link icon
     has launched a new developer portal, powered by OpenAPI 3.0.
  • Stripe 
    external link icon
     provides an OpenAPI 3.0 specification for its REST APIs on GitHub.
  • British Columbia external link icon uses OpenAPI 3.0 for its government API specifications.

RepreZen API Studio Surges Ahead with OpenAPI v3

Last year, RepreZen led the way with the first native OpenAPI 3.0 editor. Today, OpenAPI design takes a big step forward in RepreZen API Studio with advanced validation, multi-file support, and comprehensive code generation, all working seamlessly with OpenAPI 2.0 and 3.0.

Code Generation, Complete and Customizable

OpenAPI Generator is a new project, based on Swagger Codegen, that provides a comprehensive set of code generators for OpenAPI 3.0. You'll find GenTemplates for client SDKs, server-side API implementations, documentation, and interchange formats, covering a wide range of programming languages and frameworks.

In fact, OpenAPI Generator has 90 code generators, ready to run with OpenAPI 3.0!

The redesigned dialogs for for new projects, new API specs, and new GenTargets now use a provider icon and filter, with improved search to quickly find the GenTarget you want. Here's what the New Generation Target UI looks like, for an OpenAPI 3.0 model: 

New GenTarget Dialog

The available GenTemplates depend on the API specification format:

  • Swagger-OpenAPI 2.0 specifications show GenTemplates from RepreZen, Swagger Codegen, and NSwag by default. GenTemplates from the OpenAPI Generator project are also available, but are excluded by default, since they overlap with Swagger Codegen.
  • OpenAPI 3.0 specifications show GenTemplates from RepreZen and OpenAPI Generator.
  • RAPID-ML specifications show GenTemplates from RepreZen and NSwag.

You can click the Providers drop-down menu to change the default filter settings:

New-GenTarget-Provider-Filter

OpenAPI 3.0 is fully supported in RepreZen's powerful codegen architecture:

  • Generate from the IDE, the command line, or CI/CD automated builds using Maven and Gradle integration. 
  • Easily configure individual code generation targets using a convenient YAML settings file.
  • Create your own custom generators using RepreZen's fully integrated, template-driven code generation framework. This gives you total freedom to generate exactly what you need, and it takes less than 2 minutes to get started.

Learn More about Codegen  

Ready for Multi‑File API Specifications

RepreZen's cutting-edge Multi‑File support now works even better with OpenAPI 3.0. You can use OpenAPI's standard $ref properties to reference schemas, parameters, and other components in an external document. Splitting a large, complex API specification into multiple documents and reusing shared definitions across APIs really helps keep your APIs in sync and your team coordinated. 

API Studio works seamlessly with projects structured in this way. Code assist, navigation, live documentation, and even code generation are all multi-file ready. And the new KaiZen OpenAPI Normalizer (formerly Swagger Normalizer) simplifies and consolidates complex multi-file projects into a single document for easy downstream code generation, documentation, and tool integration.

Normalizer Infographic (shadow)

Learn More about Multi‑File  

Advanced OpenAPI 3.0 Validation

API Studio now includes advanced OpenAPI 3.0 validation, provided by our open source KaiZen OpenAPI Parser. Earlier releases of the editor verified the essential structure, types, value ranges, and references in your OpenAPI documents. Advanced validation goes further, checking the logical rules written into the OpenAPI language specification. 

RepreZen is working directly with the OpenAPI TSC (Technical Steering Committee) to define a conformance test suite, ensuring complete tool interoperability. We're committed to full standards-compliance, and you can expect further refinements to validation in subsequent releases.

Migrating OpenAPI 2.0 Projects to 3.0

If you have Swagger-OpenAPI 2.0 documents you'd like to update to OAS3, just use the OpenAPI (YAML) GenTemplate provided by OpenAPI Generator:

  1. Make sure 2.0 documents you want to convert are in a project in your API Studio workspace. If you're new to API Studio, see the support article: 
    Importing a YAML Swagger Spec into API Studio
  2. Open the Swagger 2.0 document in the editor, and ensure that it validates without any errors or warnings.
  3. Click the button in the toolbar to Create a New Generation TargetGenTarget-128
  4. In the New Generation Target dialog, click the Provider button and check OpenAPI Generator to show its available GenTemplates. New GenTarget Show OAG (crop)
  5. Select the OpenAPI (YAML) GenTemplate, and click Finish. This will create a new GenTarget folder in your project, and will open the .gen YAML configuration file.
  6. Use the code generation drop-down menu in the toolbar to execute the OpenAPI (YAML) GenTarget. Generate OpenAPI YAML
  7. In Project Explorer, you'll find a generated subfolder under the OpenAPI (YAML) GenTarget folder. Expand this folder, and you'll find the OpenAPI YAML document there. 
  8. Use drag-and-drop or copy-and-paste to move the generated YAML file to its new home, wherever you like. If you will be doing further work on the OpenAPI 3.0 document, you can put it into the /models folder within a new or existing RepreZen Project.

Looking for Help with Your API Strategy?

If you need expert guidance or high-caliber execution for your API program, talk to RepreZen. Our elite Professional Services team can provide hands-on training, API strategy and architecture, toolchain customization, or end-to-end API design, development and delivery. 

Let's Talk!


Topics: Code Generation, Swagger, OpenAPI, RepreZen API Studio, Multi-File, Release, KaiZen OpenAPI Editor, KaiZen OpenAPI Normalizer, Industry Trends, KaiZen OpenAPI Parser

Welcome!

At RepreZen, we're building our business on two things:  thought leadership in API design, and great conversations.

This blog is one of many places where we'll have illuminating, mutually enriching conversations with our customers, partners, and the software community at large.  Please chime in with your thoughts and let's get started!

RepreZen API Studio - Free Trial!


Installing RepreZen API Studio is easy!  Here's how it works:

number_circle_1   Submit the trial registration form.
number_circle_2   Check your inbox for download instructions.
number_circle_3   Download and run the automated installer.

 

System Requirements

 

RepreZen API Studio runs on the following operating systems:

  • 64-bit Windows 7, 8.0 and 8.1
  • Mac OS X 10.7 or higher
RepreZen API Studio requires 64-bit Java 8 or higher.