Using Visual editor in OpenAPI builder

Scrolling the canvas

The canvas shows the OpenAPI specification in a block-based form. There is a block for each endpoint with an HTTP method and a path, and nested blocks for parameters and responses. For more information on blocks, see Blocks.

Opening the palette

The palette shows all the blocks that can be added to an OpenAPI specification, grouped into categories such as API Endpoints, Types, Values, References and Connectors.

Opening the text view

The block-based view on the canvas corresponds to a text-based JSON view of the OpenAPI specification. The text view of the start block shows the entire OpenAPI specification, whereas the text view of any other block shows just the excerpt of the specification for that block.

• Click the pencil icon to open the text view of a block. Re-click to close the text view.

Opening the block configuration fly-out

To open a configuration fly-out:

• Click the gear icon of a block. Re-click the icon to close the configuration fly-out.

Creating a top-level block

The top-level editor has a top-level palette. To create a block in a configuration:

• Drag it from the palette and drop it onto the top-level canvas.

Creating a block in a configuration flyout

A configuration flyout has its own embedded palette. To create a block in a configuration:

• Drag it from the flyout's palette and drop it onto the flyout's canvas.

Updating blocks

To update a block:

• Select one of its text fields and then type the new value.

Deleting blocks

To delete a block, use any of the following methods:

• Select the block and then press the Delete key on your keyboard.
• Right-click the block and choose Delete from the menu.

Removing the edits

You can undo edits (whether automatic edits from AI suggestions or manual edits) by any of the following methods:

• Press the keyboard shortcut Ctrl-z
• Right-click the background and choose Undo from the menu.

Updating JSON text

You can create, update, or delete blocks from the textual JSON view.

• Do the updates, then click Apply Changes.

The Apply changes button is only enabled when the JSON is error-free. If you get errors, you can either resolve the errors and apply changes, or you can click the edit icon to discard textual changes and to close the text flyout.

Endpoint blocks

Endpoint blocks specify API operations by configuring the operation method and a path. They are shaped with a notch at the top and a bump at the bottom. An endpoint block can be snapped into the bottom of the start block or another endpoint block.

The endpoint block has C-shaped holes to snap in type blocks for parameters, responses, and (for certain methods) a request body. A type block used as a parameter gains a location, a name, and a "required?" flag. A type block used as a response gains an HTTP Status code. An endpoint might have multiple parameters or responses, but at most one request body.

Type blocks

Type blocks specify JSON schemas. They are shaped with a notch at the top and, when used in a context where multiple schemas are expected, a bump at the bottom. A type block can be snapped into the C-shaped holes of an endpoint block, an array type block, an object type block, and certain connector blocks. A type block can also be snapped into the bottom of a definition block.

• Type for an enum. It lists a fixed set of values. For example: ["red", "green", "blue"]. An enum block has female jigsaw connectors on the right where value blocks can be snapped in. Use the "+"/"-" to change the number of values.

The following JSON script shows an example for enum type:

{
  "Color": {
    "type": "string",
    "enum": [
      "Red",
      "Green",
      "Blue"
    ]
  }
}

• Type for strings of text. For example: Hello world!.

The following JSON script shows an example for string type:

{
  "node_id": {
    "type": "string",
    "example": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "x-ibm-grounded-description": false
  }
}

• Type for integers. Whole numbers, for example: 3, 42, 0, -2048.

The following JSON script shows an example for Integer type:

{
  "id": {
    "type": "integer",
    "example": 1,
    "x-ibm-grounded-description": false
  }
}

• Type for numbers. Floating points or whole numbers, for example: 3, 2.99, 0, -123.456.

The following JSON script shows an example for Number type:

{
  "Value": {
    "type": "number",
    "example": 1.5,
    "x-ibm-grounded-description": false
  }
}

• Type for boolean values. For example: true or false.

The following JSON script shows an example for Boolean type:

{
  "site_admin": {
    "type": "boolean",
    "x-ibm-grounded-description": false
  }
}

• Type for arrays of items. For example: [1,2,3]. The "type: array" block itself is C-shaped, so another type block can be snapped in to specify the type of items that are allowed.

The following JSON script shows an example for Array type:

{
  "events": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "example": [
      "deployment"
    ],
    "x-ibm-grounded-description": false
  }
}

• Type for objects, which are mappings from string keys to JSON values. The "type: object" block itself is C-shaped, so other type blocks can be snapped in for the properties. A type block nested into a "type: object" as a property gains a key (usually as a "Name") and a "required?" flag.

The following JSON script shows an example for Object type:

{
  "permissions": {
    "type": "object",
    "example": {
      "deployments": "write",
      "metadata": "read",
      "pull_requests": "read",
      "statuses": "read"
    }
  }
}

• The null type allows only the null value.

The following JSON script shows an example for Null type:

{
  "type": [
    "string",
    "null"
  ],
  "maxLength": 255
}

Value blocks

Value blocks specify JSON values. They are shaped with a male jigsaw connector on the left. Value blocks can be snapped into female jigsaw connectors to specify default values or example values in the configuration fly-out of other blocks. A value block can also be snapped into female jigsaw connectors of an array value block, an object value block, or an enum block.

• A string of text. For example: Hello, world!.

• A whole number. For example: 3, 42, 0, -2048.

• A floating point or a whole number. For example: 3, 2.99, 0, -123.456.

• The value is true if the check-box is selected otherwise it is false. For example: true.

• An array of values (an instance of an array type). The array value block itself has female jigsaw connectors on the right, so other value blocks can be snapped in for the items. Use the "+"/"-" to change the number of items.

• A mapping from string keys to values (an instance of an object type). The object value block itself has female jigsaw connectors on the right, so other value blocks can be snapped in for the properties. A value block nested into an object value as a property gains a string key ("Name"). Use the "+"/"-" to change the number of properties.

• The null value (an instance of type null).

Reference blocks

Reference blocks refer to a schema definition, which the editor shows in tabs. They are shaped with a notch at the top and, when used in a context where multiple schemas are expected, a bump at the bottom. A reference block can be used wherever the definition it refers to is expected. In other words, a reference that points to a type block can snap into any place type blocks can. Reference blocks contain a string with a URI that identifies the location of the schema definition being referenced.

Connector blocks

Connector blocks compose other blocks into schemas that act like new type blocks. They are shaped with a notch at the top and, when used in a context where multiple schemas are expected, a bump at the bottom. A connector block can be used wherever a type block can be used.

• To validate against anyOf, the data must be valid against at least one of the schemas. It is similar to a union type in some programming languages. The anyOf block itself is C-shaped, so other schemas can be snapped in for the alternatives.

• To validate against allOf, the data must be valid against all schemas. It is similar to an intersection type in some programming languages. The allOf block itself is C-shaped, so other schemas can be snapped in for the conjuncts.

• To validate against oneOf, the data must be valid against exactly one of the schemas. The oneOf block itself is C-shaped, so other schemas can be snapped in for the alternatives.

• To validate against not, the data must be invalid for the schema. The not block itself is C-shaped, so another schema can be snapped in.

• The empty schema ({}) accepts any valid JSON value. It is similar to an "Any" type in some programming languages. Not to be confused with a true boolean value, which is not a schema. The negated empty schema ({"not":{}}) does not accept any values. Not to be confused with a false boolean value, which is not a schema.

• The if, then, else block allows the application of a component schema based on the outcome of another schema. It has C-shaped holes for the condition, then-clause, and else-clause, each of which can hold at most one other schema block.