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.
Adding a New Operation
To manually define a new API operation:
- Go to the Operations tab.
- Click the green plus button at the top.
- Specify the operation name.
- Click the floppy disk button to save.
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.
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:
- Click the green plus button in the same row as the Request Body label.
- Populate the fields in the Request Body section, especially required values.
- 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.
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:
- Click the green plus button in the same row as the Parameter label.
- Populate the fields in the Parameter section, especially required values.
- 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).
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:
- Click the green plus button in the same row as the Response label.
- Populate the fields in the Response section, especially required values.
- 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:
- Click the green plus button in the same row as the Headers label.
- Populate the fields in the Headers section, especially required values.
- 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:
- Click the green plus button in the same row as the Content label.
- Populate the fields in the Content section, especially required values.
- 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.
To add a security scheme to the selected operation:
- Click the green plus button in the same row as the Security label.
- Select the security scheme in the Security Id combo box.
- 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.
To add another server that serves the selected operation:
- Expand the Server field by clicking on the Server label.
-
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.
-
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.
To add a tag to an operation:
- Expand the Tag field by clicking on its label.
- Select a tag using the Name field underneath. Tags defined in the Tags tab will be selectable.
- Click the floppy disk icon to save.