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
has standardized on OpenAPI 3.0 for greater alignment and interoperability across national, provincial and municipal agencies.
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
has launched a new developer portal, powered by OpenAPI 3.0.
provides an OpenAPI 3.0 specification for its REST APIs on GitHub.
- British Columbia 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:
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:
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.
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.
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:
- 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
- Open the Swagger 2.0 document in the editor, and ensure that it validates without any errors or warnings.
- Click the button in the toolbar to Create a New Generation Target.
- In the New Generation Target dialog, click the Provider button and check OpenAPI Generator to show its available GenTemplates.
- 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.
- Use the code generation drop-down menu in the toolbar to execute the OpenAPI (YAML) GenTarget.
- 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.
- 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.