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

Start my Free Trial

Contents:

About JSON and YAML Formats
Importing a JSON OpenAPI Document into API Studio
Opening a JSON OpenAPI Document in the Editor
Reformatting a JSON OpenAPI Document to YAML

Exporting a YAML-Formatted OpenAPI Document  to JSON Format


About JSON and YAML Formats


The OpenAPI Specification, supports two different syntax forms:  JSON, and YAML. YAML supports a flow syntax which 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 block 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 syntax for OpenAPI v2 (Swagger) and v3 document formats, and is most widely supported by OpenAPI editors. KaiZen OpenAPI Editor, RepreZen's open source editor, allows you to edit OpenAPI documents inside RepreZen API Studio. While KaiZen Editor has limited support for JSON format, it is optimized for YAML editing.


Sometimes you need to use OpenAPI documents that are in JSON format. This article shows you how to import an OpenAPI JSON file into API Studio, open it in the appropriate editor, and convert it to YAML format.


Importing a JSON OpenAPI Document into API Studio


To import a JSON-formatted OpenAPI Document, 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 OpenAPI JSON document 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 OpenAPI 2.0 Document (called a "Swagger Spec" in the KaiZen Editor and RepreZen API Studio environments) in the models folder of your project.  Since you'll be pasting an existing OpenAPI document 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 OpenAPI Document in the Editor


If you imported the JSON OpenAPI document using File Import or drag-and-drop, your file will have a .json extension, and won't be recognized automatically as an OpenAPI file. If you double-click to open the file from Project Explorer, it will open in a standard JSON editor, without OpenAPI validation, code assist, live views and other API-specific functionality.
  • If you plan to convert the OpenAPI Document 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 editor as follows: 
  1. Right click the JSON OpenAPI document in Project Explorer.

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

  3. Choose Swagger Editor or OpenAPI v3 Editor from the list, depending on the OpenAPI version of your document.


Once you've opened the JSON document in the appropriate OpenAPI 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 OpenAPI specification. Since YAML is a superset of JSON, valid YAML is not necessarily valid JSON.

Reformatting a JSON OpenAPI Document to YAML


Once your OpenAPI JSON spec is open in the correct 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 OpenAPI document is in standard YAML format, and you can edit safely in the OpenAPI editor.

Note: The formatter is available to normalize formatting in OpenAPI 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 OpenAPI files, and why the OpenAPI 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 document to JSON format, using the "Swagger [JSON]" generation template for OpenAPI v2, or the "OpenAPI [JSON]" template for OpenAPI v3.


To create and run the JSON converter GenTemplate:

  1. With your OpenAPI 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 the JSON conversion template. For OpenAPI v2, this will be the Swagger [JSON] GenTemplate provided by Swagger-Codegen. For OpenAPI v3, you'll use the OpenAPI [JSON] GenTemplate provided by OpenAPI-Generator. After selecting the appropriate GenTemplate, 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.