A Quick Look at the User Interface
The Docs to OpenAPI plugin was made to be as compact, intuitive, and powerful as possible. Let's take a quick look and explore the different navigable spaces in this application!
Familiarize yourself with the OpenAPI specification
For those unacquainted with the OpenAPI specification, the Docs to OpenAPI plugin can easily seem overwhelming and intimidating. The numerous fields and menus, on top of the technical terms presented by the application can be a little confusing. An understanding of the OpenAPI specification can greatly better your experience with this plugin, as most (if not all) fields have direct counterparts in the OpenAPI specification.
The Docs to OpenAPI plugin's main menu refers to the top-most (in terms of hierarchy) set of navigation items. The main menu is shown as the first set of menu items in the user interface.
From left to right, it is comprised of the (1) Crawler, (2) OpenAPI, (3) TORO Marketplace, (4) Settings, and (5) Help menus. They are shown as tabs and these tabs help the user navigate between the plugin's "pages". Every tab will display a different set of components relevant to the feature they present; some are simple, some are more complex and even contain nested menus.
Hover over field labels to see their description or purpose
You can feed your API's information to the Docs to OpenAPI plugin manually or have Docs to OpenAPI do the work for you via crawling the page. The information obtained will be used in generating the OpenAPI schema for your API.
The Crawler tab shows the current Crawler configuration. It has a toolbar and four nested tabs labeled (from left to right) Operation, Request Body, Parameter, and Response.
Complete guide to crawling
Learn everything about configuring the crawler - from performing basic extractions using 'vanilla' fields to using custom scripts to do advanced crawling - in the Crawler section.
The Crawler tab contains a handy set of tools at the top to help you (1) save your configuration, (2) view logs, (3) delete the current crawler configuration, (4) copy the generated OpenAPI specification to the clipboard, (5) export the current crawler configuration, (6) import and load a different crawler configuration, and (7) show the Strategy and Scripts tabs.
The Operation, Request Body, Parameter, and Response tabs contain fields for identifying API operations, request bodies of API operations, parameters of API operations, and responses of API operations, respectively.
Docs to OpenAPI uses CSS selectors to identify which values should go into the schema. In each of these tabs, the user is asked to provide the CSS selector for each API operation, request body, parameter, or response property. Required fields are marked by a red asterisk (*).
If CSS selectors aren't enough to extract the the required value from the HTML page, the
Exclude fields may be used for a more advanced configuration.
Run Crawler button is present in every tab
The Run Crawler button is constantly present at the bottom of every tab so that you can trigger the crawler conveniently.
The OpenAPI tab is used to configure the API's (1) operations, (2) schemas, (3) tags, (4) security, (5) servers, and (6) general information. Use the (7) Clear Data button for clearing all entries displayed in this tab.
TORO Marketplace Tab
The TORO Marketplace tab allows you to upload your configuration to the TORO Marketplace or download the configurations other TORO Marketplace users have posted. To do either of these actions, you would need to log in to your TORO Marketplace account.
If your account is not logged in yet, Docs to OpenAPI will display a login form. But after successfully logging in, you should be presented with fields relevant to importing and exporting configurations.
The Settings tab contains fields for further configuring the Crawler.
The Help tab contains links to resources for helping you learn more about the Docs to OpenAPI plugin. From this tab, you can:
- start an interactive tour
- go to the documentation website
- go to the Q&A community