One of the important milestones on the road to full support of OpenAPI 3.0 in API Studio was the incorporation of a new, 3.0-compliant release of Swagger UI. This milestone was achieved in release 1.5.18, with the introduction of both the Swagger UI v3 live view and the Swagger UI v3 GenTemplate.
What's better about the new Swagger UI v3 implementation?
The new live view and GenTemplate work with both OpenAPI 3.0 and OpenAPI 2.0 (a.k.a. Swagger) documents. They are based the latest Swagger UI version, which is a complete rewrite boasting a new modern look-and-feel and a highly responsive UI.
What if I want to use the previous version?
The old Swagger UI live view and GenTemplate are both still available, though support (bug fixes, etc.) for the version of Swagger UI on which they are based is likely to be sparse going forward.
The old GenTemplate is now named "Swagger UI v2" in the GenTemplate menu, while the new GenTemplate is named "Swagger UI v3" Any of your existing GenTargets based on the old v2 GenTemplate will continue to use that GenTemplate; you must create new GenTargets if you wish to switch to the new v3 GenTemplate.
N.B. If you create a new "Swagger UI v3" GenTarget and accept the wizard defaults, your prior v2 GenTarget will be silently replaced with a new v3 GenTarget. If you wish to preserve your existing v2 GenTarget, you should first rename it in the Project Explorer.
The old Swagger UI live view is now called "Swagger UI v2 View." You can open it using the Quick Access box in the toolbar, or by using Window > Show View > Other... in the toolbar. Either way, you will end up with the old and new live views in separate tabs, and this will persist when you exit and relaunch API Studio.
Why doesn't the Mock Service work?
Early releases of the Swagger UI did not yet support the "Try it out" feature for OpenAPI 3.0 documents, but the feature works on 2.0 (Swagger) documents. Therefore, you will not see an on/off switch for the Mock Service when editing a 3.0 document, but you will continue to see it when editing a 2.0 document. The Mock Service will work correctly with 2.0 documents, in the old and new live views. More recently Swagger UI has enabled "Try it out" for OpenAPI 3.0 documents. Mock Service for 3.0 documents will follow shortly.
Can I use the same GenTemplate parameters with v2 and v3?
There are a number of options that were supported in the old Swagger UI implementation, and which we exposed as GenTarget parameters in the old Swagger UI GenTemplate. These parameters are still available in the Swagger UI v2 GenTemplate.
The Swagger UI option set has changed significantly with the new release, and most of the Swagger UI v2 GenTarget parameters are not present for v3 GenTargets. Some parameters that we can provide for the new Swagger UI v3 option set are not yet available in the GenTemplate, but we plan to provide them in an upcoming release. It is likely that several options formerly available in Swagger UI v2 will not reappear in the new version, and corresponding GenTarget parameters will therefore not reappear in the new Swagger UI v3 GenTemplate. We will do our best to support evolving Swagger UI options in convenient GenTarget parameters as we move forward.