Skip to content

Configuring API Operations

A RESTful API is typically comprised of multiple operations. An operation is a function callable upon request. In the OpenAPI specification, operations are described through Operation Objects.

The plugin maps acquired operation models to Operation Objects when generating an OpenAPI schema. The Operations tab is where you can view existing operation models, obtained through crawling or entered by the user using the form in the same tab. In this section, we'll take a look at these models, their properties, and how to configure them through the user interface.

The Operations tab

Adding a New Operation

To manually define a new API operation:

  1. Go to the Operations tab.
  2. Click the green plus button at the top.
  3. Specify the operation name.
  4. Click the floppy disk button to save.

Adding a new operation

Once your operation is existing, you can proceed to editing its field values. To shuffle between multiple operations, use the double arrow head buttons.

Fields

The following fields are present in the Operations tab:

Name Required Description Example
Name Yes A unique string identifying the operation. This is usually named after an action and written in camelCase or PascalCase, much like an OOP method. A maximum of 255 characters is allowed. getAccount
Description No A brief description of what the operation does. A maximum of 255 characters is allowed. Get an existing acount
Method Yes The operation's HTTP request method, which indicates the type of operation to be performed. In the plugin, this field is displayed as a combo box with the options: GET, POST, DELETE, PUT, OPTIONS, HEAD, and PATCH. GET
Path Yes The URL where the operation can be accessed. This URL is assumed to be relative and will be appended to the server URL. Path parameters must be declared using curly braces ({}). /account/{id}
Request Body No Payload of the HTTP request when sent to the server.
Parameter No Describes inputs that can be sent along with a request when an operation call is made.
Responses No The expected response of the server after it receives and interprets a request.
Security No Security mechanisms for this operation.
Servers No The servers where this operation is accessible.
Tags No Tags associated with this operation. Tags can be used for the logical grouping of operations.

Request Body

HTTP requests are sent to HTTP servers in a specific format; and among the data it can carry is a message body. A request body is optional (e.g. a request body is not present in most GET, OPTIONS, or DELETE requests), but for most PUT or POST requests, it is provided in order to feed the server with input required to create or update a resource.

Request Body section, as seen in the Operations tab

In the plugin, the Request Body field is used to specify the selected operation's expected request body. A request body is an object, described through the following fields:

The OpenAPI specification allows only one request body per operation

An Operation Object can only have one Request Body Object, but the body can be in multiple formats. To shuffle between formats, use the double arrow head buttons on the side of the top-level combo box.

Name Required Description
Description No A brief explanation of the contents of the request body.
Media Type Yes Content type of the request payload. Example: application/json.
Content Yes The structure of the request payload, described through a schema. This field is displayed as a combo box, where you could search and select a schema from the list of existing schemas.
Required No Indicates whether or not the operation always requires a request payload to be sent.
Array No Indicates whether or not the payload presents an array of values at the root level of the document.

To set the selected operation's request body:

  1. Click the green plus button in the same row as the Request Body label.
  2. Populate the fields in the Request Body section, especially required values.
  3. Click the floppy disk icon to save.

Parameter

The Parameter field is used to specify the list of supported parameters for a selected operation. Parameters are optional, so an operation can have none of it, or multiple ones. To shuffle through parameters, use the double arrow heads on the side of the top-level combo box.

Parameter section, as seen in the Operations tab

Each parameter is defined using the following fields:

Name Required Description Example
Name Yes The name of the parameter. threadId
Location Yes The location of the parameter, as specified in the API documentation. This can be any of the following values: QUERY for query string parameters; PATH for path parameters; HEADER for custom headers; and COOKIE for cookie parameters passed in the cookie header. PATH
Description No A verbose explanation of what the parameter is for. The ID of the thread where the comment belongs to.
Schema No Defines the parameter's data type. This can be any of the primitive types, or custom types defined through schemas. integer
Required No Indicates whether this parameter is mandatory or not.
Allow Empty Value No Indicates whether this parameter's value can be empty or not. This field is used only for query parameters.
Deprecated No Indicates whether this parameter is deprecated or not.
Array No Indicates whether this parameter can be specified multiple times or not. E.g. if the name query parameter can be used to hold multiple values: ?name=John&name=Jane&name=Jim.

Likewise, to add a new parameter to the currently selected operation:

  1. Click the green plus button in the same row as the Parameter label.
  2. Populate the fields in the Parameter section, especially required values.
  3. Click the floppy disk icon to save.

Response

An HTTP response is the information a server sends in response to a request sent earlier by a client. An operation can have more than one type of response (one per status code).

Response section, as seen in the Operations tab

The Response field is used to specify the list of responses that clients can expect from the selected operation. Each response is described through the following fields:

Name Required Description Example
Status Code Yes A three-digit code used to indicate the status of the executed operation. Use the combo box to search and select available status codes. 200
Description Yes A string describing the response. OK
Headers No Used to pass additional information to the client about the call.
Content No Payload of the response.

To add a response to the selected operation:

  1. Click the green plus button in the same row as the Response label.
  2. Populate the fields in the Response section, especially required values.
  3. Click the floppy disk icon to save.
Only the Status Code and Description field are required

You can add headers and set the response body, but these are both optional.

Response Headers

API responses can include custom headers to provide additional information regarding the result of the API call. The Headers field is used to specify the headers associated with the selected response. This field is split further into four fields:

Name Required Description
Name Yes The name of the header.
Schema Yes The data type used by the header, which can either be a primitive or a custom object.
Description No A brief description of the header.
Array No Indicates whether or not the selected schema will be used as an array. Check this field if true.

To add a new response header:

  1. Click the green plus button in the same row as the Headers label.
  2. Populate the fields in the Headers section, especially required values.
  3. Click the floppy disk icon to save.

Response Content

Like requests, responses can also have a body. To set potential response payloads for the selected response, use the Content field (under the Response section).

Response payloads can vary in format

A single Response Object can set multiple payload formats. To shuffle between formats, use the double arrow head buttons on the side of the top-level combo box.

Name Required Description
Media Type Yes The returned response's content type. For example, application/json.
Schema Yes The data type of the response content, which can either be a primitive or a custom object.
Array No (default provided) Indicates whether or not the selected schema will be used as an array. Check this field if true.

To add new response content:

  1. Click the green plus button in the same row as the Content label.
  2. Populate the fields in the Content section, especially required values.
  3. Click the floppy disk icon to save.

Security

The Security field is used to specify the security schemes implemented in an operation. To shuffle between schemes, use the double arrow head buttons on the side of the top-level combo box.

Security section, as seen in the Operations tab

To add a security scheme to the selected operation:

  1. Click the green plus button in the same row as the Security label.
  2. Select the security scheme in the Security Id combo box.
  3. Click the floppy disk icon to save.
An existing security scheme is required

To add a security scheme to an operation, the security scheme must first be defined in the Security tab.

Servers

It's possible for an API to be served over multiple servers. The Servers field lets us know which servers provide the selected operation.

Servers section, as seen in the Operations tab

To add another server that serves the selected operation:

  1. Expand the Server field by clicking on the Server label.
  2. Select the server you want using the Server Url combo box.

    Where can I define servers?

    Before you can select a server, the server must be defined in the Servers tab.

  3. Click the floppy disk icon to save.

Tag

Tags are used typically to group alike operations together. A single operation can be assigned multiple tags. The Tag field is used for setting the selected operation's tags.

Tag section, as seen in the Operations tab

To add a tag to an operation:

  1. Expand the Tag field by clicking on its label.
  2. Select a tag using the Name field underneath. Tags defined in the Tags tab will be selectable.
  3. Click the floppy disk icon to save.