Powerful IDE for API-first design, documentation and development.

Start my Free Trial

Contents:

About JSON and YAML Formats
Importing a JSON Swagger File into API Studio
Opening a JSON Swagger Spec in the Swagger Editor
Reformatting a JSON Swagger Spec to YAML

Exporting a YAML-Formatted OpenAPI Document  to JSON Format


About JSON and YAML Formats


Swagger, now the OpenAPI Specification, supports two different syntax forms:  JSON, and YAML. YAML is in most respects a superset of JSON, so valid JSON is also valid YAML.  But YAML also includes its own, more concise and readable syntax.


The following JSON and YAML snippets are equivalent:


JSON Example:

"/pets" : {

 "get" : {

 "tags" : [ "pets" ],

 "summary" : "List all pets",

 "operationId" : "listPets",

"parameters" : [ {

  "name" : "limit",

   "in" : "query",

 "description" : "How many items to return at one time (max 100)",

  "required" : false,

  "type" : "integer",

  "format" : "int32"

  } ],

 "responses" : {

   "200" : {

 "description" : "An paged array of pets",

  "schema" : {

  "$ref" : "#/definitions/Pets"

  },

 "headers" : {

 "x-next" : {

 "type" : "string",

 "description" : "A link to the next page of responses"

  }

 }

  }

 }



YAML Example

/pets:

  get:

   tags:

   pets

  summary: List all pets

  operationId: listPets

   parameters:

   - name: limit

   in: query

    description: How many items to return at one time (max 100)

  required: false

  type: integer

  format: int32

   responses:

   '200':

  description: An paged array of pets

   schema:

  $ref: '#/definitions/Pets'

   headers:

   x-next:

   type: string

   description: A link to the next page of responses

  

You can see that the YAML example doesn't need to use quotes, curly braces, and square brackets. YAML can accept standard JSON syntax, with all of these extra characters.  But the usual YAML style, shown here, uses simplified delimiters and indentation to denote the structure.


YAML is the preferred format for Swagger-OpenAPI, and is most widely supported by Swagger editors. KaiZen OpenAPI Editor, RepreZen's open source editor, allows you to edit Swagger files inside RepreZen API Studio. While KaiZen Editor has limited support for JSON format, it is optimized for YAML editing.


Sometimes you need to use Swagger files that are in JSON format. This article shows you how to import a Swagger JSON file into API Studio, open it in the Swagger Editor, and convert it to YAML format.


Importing a JSON Swagger File into API Studio


To import a JSON-formatted Swagger Spec, you need to have a project to contain it.  Then you can drag-and-drop, copy-and-paste, or use the File Import command to get the Swagger JSON spec into the models folder of the project.

Importing with Drag-and-Drop

 

Drag the file you want to import into the models folder of the project inside API studio, or the underlying models folder in the filesystem.

 

If you chose to copy the file using the filesystem, you need to refresh the folder in API Studio.  Do this by selecting the folder in API Studio and pressing the refresh key (F5 on Windows), or right-clicking on the project in Project Explorer, and clicking the Refresh command.

 

If you chose to copy the file by dropping it into the folder inside API Studio, you may be asked whether you want to copy or link the file. Choose an option based on your needs. Copy is usually a safe choice.


Importing with Copy and Paste

  1. Use the toolbar button, menu command or dashboard link to create a new Swagger spec in the models folder of your project.  Since you'll be pasting an existing Swagger spec into the editor, you can choose "No Content" as the initial content.

  2. Paste the content into the editor.

Importing with the File Import Command

  1. In Project Explorer, select the models folder in the project you want to use.

  2. From the File menu, choose Import...

  3. Open the General folder and choose File System.

  4. Navigate to the folder containing the JSON file you want to import, choose the file, and click Finish.



Opening a JSON Swagger Spec in the Swagger Editor


If you imported the JSON Swagger spec using File Import or drag-and-drop, your file will have a .json extension, and won't be recognized automatically as a Swagger file.  If you double-click to open the file from Project Explorer, it will open in a standard JSON editor, without Swagger validation, code assist, live views and other API-specific functionality.
  • If you plan to convert the Swagger spec from JSON to the recommended YAML format, you can rename the file in Project Explorer by selecting it and using the rename hot key (F2 on Windows), or choosing Rename... from the right-click context menu.

  • If you intend to keep the file in JSON format, you can open it in the Swagger editor as follows: 
  1. Right click the JSON Swagger spec in Project Explorer.

  2. From the Open With... submenu, choose Other...

  3. Choose Swagger Editor from the list.


Once you've opened the Swagger JSON file in RepreZen's Swagger editor, you'll see that syntax highlighting, validation, code assist, live views and the Mock Service all work as expected.

However, code assist will insert new content in YAML format, and validation won't ensure that your document stays in valid JSON format.  It will only ensure that your document is valid YAML, and that it conforms to the Swagger specification.  Since YAML is a superset of JSON, valid YAML is not necessarily valid JSON.

Reformatting a JSON Swagger Spec to YAML


Once your Swagger JSON spec is open in the Swagger editor, you can reformat it to concise YAML style as follows:
  1. Click in the Quick Access toolbar in the upper-right side of the API Studio application window:



  2. From the Commands category, click the Format command.



Now your Swagger spec is in standard YAML format, and you can edit safely in the Swagger editor.

Note: The formatter is available to normalize formatting in Swagger YAML files, but we do not recommend using it except for JSON conversion. Formatting removes YAML comments, which are a unique feature of YAML, and not part of the JSON representation. This is why we do not recommend using the formatter on YAML Swagger files, and why the Swagger editor does not have a shortcut key for the format command.


Exporting a YAML-Formatted OpenAPI Document  to JSON Format

You can easily generate your YAML-formatted OpenAPI 2.0 document to JSON format, using the "Swagger [JSON]" generation template.


Note: The "Swagger [JSON]" generator is provided as part of the open source Swagger-Codegen project. At the time of this writing, the latest Swagger-Codegen release does not yet support OpenAPI 3.0. It is expected that Swagger-Codegen will be releasing an OpenAPI 3.0-compatible version, and that this will include a generator for JSON format. 


To create and run the Swagger [JSON] GenTemplate:

  1. With your Swagger-OpenAPI 2.0 specification open in the editor, click the New Generation Target button on the toolbar.

  2. In the New Generation Target dialog, set the GenTemplate to Swagger [JSON] and click Finish.

  3. RepreZen API Studio will create the GenTarget and display the .gen configuration file. You can adjust settings here, or accept the defaults. Click the Generate command in the toolbar to execute the generator.  

    The generated JSON file will appear in the generated subfolder.