Using the Exclude Field

Sometimes provided CSS selectors, no matter how specific, still select unwanted elements. This litters the resulting OpenAPI schema. When required HTML elements cannot be picked apart simply through CSS selectors, the Exclude field can be used to filter them by tag content.

The Exclude field works by ignoring the operation, request body, parameter, or response currently being crawled when the provided CSS selector picks up a value for a field that meets any of its conditions¹ for exclusion.

A condition can come in the form of a regular expression pattern or a boolean Javascript expression. For an exclusion to occur, the value of the selected element must match any of the provided patterns, or the JavaScript expression must return true for the value.

Available Properties

The Exclude field allows you access to the following properties, should you choose to provide a JavaScript expression (instead of a RegEx pattern):

• targetEl

  This is the HTML element matching the provided CSS selector.

• text

  The text obtained from targetEl.

• metadata

  This is a read-only object containing the current plugin configuration (including crawled data).

• operation

  This is also a read-only object, but contains API operation data instead; particularly the API operation tied to the field being currently crawled. This is only available in the Request Body, Parameter, and Response tabs.

Available Methods

The Exclude field allows you access to the following methods, should you choose to provide a JavaScript expression (instead of a RegEx pattern):

• log(String:text) - use this to print text to your browser's console
• error(String:text) - use this to print text to your browser's console in red to signal the occurrence of an error

Example

Consider the following HTML table defining supported path and body parameters together:

<table class="parameters">
    <thead>
        <tr>
            <th>Name</th>
            <th>Located In</th>
            <th>Description</th>
            <th>Required</th>
            <th>Schema</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>threadId</td>
            <td>path</td>
            <td>The ID of the thread where the comment belongs to</td>
            <td>Yes</td>
            <td>integer</td>
        </tr>
        <tr>
            <td>body</td>
            <td>body</td>
            <td>The comment to create</td>
            <td>Yes</td>
            <td>
                <pre>
                    <!-- Sample JSON payload -->
                    <!-- Omitted for briefness -->
                </pre>
            </td>
        </tr>
    </tbody>
</table>

In the plugin's Parameter tab, we would only need to scan path and query parameters; so our task for this example is to exclude body parameters. To do this, we'll be using the Exclude field:

Label	Selector	Exclude
Location	td:nth-child(2)	return text === 'body';

The above configuration tells the Crawler to look for the location of a parameter in the second column of each row (every row describes one parameter). If the second column's value is the string "body", then the Crawler would ignore the current parameter entry. For our example, this means it would ignore the body parameter, but would still take in the threadId parameter.

---

1. The Exclude field can hold multiple conditions for exclusion. ↩