Attributes   |   Methods   |   Events   |   Slots   |   Advanced Styling   |   Vendor Extensions

Attributes

General   |   Colors & Fonts   |   Navigation Bar   |   Layout   |   Sections   |   API Server
General
spec-url url of the OpenAPI spec to view (empty)
update-route Allowed: true | false setting true will update the url on browser's location whenever a new section is visited either by scrolling or clicking true
route-prefix routes for each operation/api is generated based on the api path. however you may add a custom prefix to these routes to support third party routing needs #
sort-tags Allowed: true | false To list tags in alphabetic order, otherwise tags will be ordered based on how it is specified under the tags section in the spec. false
sort-endpoints-by Allowed: path | method | summary | none Sort endpoints within each tag by path, method or summary. none leaves the sort order unmodified.  |  Example path
heading-text Heading text on top-left corner (empty)
goto-path Initial location on the document (identified by method and path) where you want to go after the spec is loaded.
goto-path should be in the form of {method}-{path}
for instance you want to scrollTo GET /user/login you should provide the location as get-/user/login 		(empty)
fill-request-fields-with-example Allowed: true | false Request fields will be filled with example value (if provided in spec) true
UI Colors and Fonts
theme Allowed: light | dark
Is the base theme, which is used for calculating colors for various UI components. 'theme', 'bg-color' and 'text-color' are the base attributes for generating a custom theme 		dark
bg-color Hex color code for main background
Dark Theme
#333
Light Theme
#fff
text-color Hex color code for text
Dark Theme
#bbb
Light Theme
#444
header-color Hex color code for the header's background
#444444
primary-color Hex color code on various controls such as buttons, tabs
#FF791A
load-fonts Allowed:true | false RapiDoc will attempt to load fonts from CDN, if this is not intended, then set this to false. true
regular-font Font name(s) to be used for regular text "Open Sans", Avenir, "Segoe UI", Arial, sans-serif
mono-font Font name(s) to be used for mono-spaced text Monaco, 'Andale Mono', 'Roboto Mono', 'Consolas' monospace
font-size Allowed: default | large | largest
sets the relative font sizes for the entire document  |  Example 		default
use-path-in-nav-bar Allowed: true | false set true to show API paths in the navigation bar instead of summary/description  |  Example false
nav-bg-color Navigation bar's background color  |  Example
nav-text-color Navigation bar's Text color
nav-hover-bg-color background color of the navigation item on mouse-over
nav-hover-text-color text color of the navigation item on mouse-over
nav-accent-color Current selected item indicator
nav-item-spacing Allowed: default | compact | relaxed Controls navigation item spacing  |  Example default
UI Layout & Placement
layout Allowed: row | column Layout helps in placement of request/response sections. In column layout, request & response sections are placed one below the other, In row layout they are placed side by side. This attribute is applicable only when the device width is more than 768px and the render-style is 'view'. row
render-style Allowed: read | view | focused - determines display of api-docs. Currently there are three modes supported.
  • view friendly for quick exploring (expand/collapse the section of your interest)  |  Example
  • read suitable for reading (like a continuous web-page)  |  Example
  • focused similar to read but focuses on a single endpoint at a time (good for large specs)  |  Example
'read' - more suitable for reading 'view' more friendly for quick exploring 		read
on-nav-tag-click Allowed: expand-collapse | show-description - applies only to focused render-style. It determinses the behavior of clicking on a Tag in navigation bar. It can either expand-collapse the tag or take you to the tag's description page. expand-collapse
schema-style Allowed: tree | table - Two different ways to display object-schemas in the responses and request bodies  |  Example tree
schema-expand-level Schemas are expanded by default, use this attribute to control how many levels in the schema should be expanded  |  Example 999
schema-description-expanded Allowed: true | false - Constraint and descriptions information of fields in the schema are collapsed to show only the first line. Set it to true if you want them to fully expanded false
schema-hide-read-only Allowed: always | never | (combination of: post | put | patch) - read-only fileds in request schemas is always hidden but are shown in response.
If you do not want to hide read-only fields or hide them based on action you can configure this setting to 'never' or any combination of post | put | patch to indicate where to hide
Schemas in response section is not affected by this setting.  |  Example 		always
schema-hide-write-only Allowed: always | never - write-only fileds in response schemas is always hidden but are shown in request.
If you do not want to hide write-only fields then set to 'never'
Schemas in request section is not affected by this setting.  |  Example 		always
default-schema-tab Allowed: model | example - The schemas are displayed in two tabs - Model and Example. This option allows you to pick the default tab that you would like to be active model
response-area-height Allowed: valid css height value such as 400px, 50%, 60vh etc - Use this value to control the height of response textarea 300px
Hide/Show Sections
show-info show/hide the documents info section
Info section contains information about the spec, such as the title and description of the spec, the version, terms of services etc. In certain situation you may not need to show this section. For instance you are embedding this element inside a another help document. Chances are, the help doc may already have this info, in that case you may want to hide this section. 		true
info-description-headings-in-navbar Include headers from info -> description section to the Navigation bar (applies to read mode only)
Will get the headers from the markdown in info - description (h1 and h2) into the menu on the left (in read mode) along with links to them. This option allows users to add navigation bar items using Markdown  |  Example 		false
show-components show/hide the components section both in document and menu (available only in focused render-style)
Will show the components section containing schemas, responses, examples, requestBodies, headers, securitySchemes, links and callbacks 		false
show-header show/hide the header.
If you do not want your user to open any other api spec, other than the current one, then set this attribute to false		 true
allow-authentication Authentication feature, allows the user to select one of the authentication mechanism thats available in the spec. It can be http-basic, http-bearer or api-key. If you do not want your users to go through the authentication process, instead want them to use a pre-generated api-key then you may hide authentication section by setting this attribute to false and provide the api-key details using various api-key-???? attributes. true
allow-spec-url-load If set to 'false', user will not be able to load any spec url from the UI. true
allow-spec-file-load If set to 'false', user will not be able to load any spec file from the local drive. This attribute is applicable only when the device width is more than 768px, else this feature is not available true
allow-spec-file-download If set to 'true', it provide buttons in the overview section to download the spec or open it in a new tab. false
allow-search Provides quick filtering of API true
allow-advanced-search Provides advanced search functionality, to search through API-paths, API-description, API-parameters and API-Responses  |  Example true
allow-try The 'TRY' feature allows you to make REST calls to the API server. To disable this feature, set it to false.  |  Example true
allow-server-selection If set to 'false', user will not be able to see or select API server (Server List will be hidden, however users will be able to see the server url near the 'TRY' button, to know in advance where the TRY will send the request). The URL specified in the server-url attribute will be used if set, else the first server in the API specification file will be used. true
allow-schema-description-expand-toggle Allowed: true | false allow or hide the ability to expand/collapse field descriptions in the schema true
API Server & calls
server-url OpenAPI spec has a provision for providing the server url. The UI will list all the server URLs provided in the spec. The user can then select one URL to which he or she intends to send API calls while trying out the apis. However, if you want to provide an API server of your own which is not listed in the spec, you can use this property to provide one. It is helpful in the cases where the same spec is shared between multiple environment say Dev and Test and each have their own API server. (empty)
default-api-server If you have multiple api-server listed in the spec, use this attribute to select the default API server, where all the API calls will goto. This can be changed later from the UI (empty)

When providing API key using RapiDoc element, make sure that you provide all the 3 attributes with some default values api-key-name, api-key-location & api-key-value
Set api-key-value to "-" if you are unsure of its value, and like to fill in later using JavaScript

api-key-name Name of the API key that will be send while trying out the APIs (empty)
api-key-location Allowed: header, query - determines how you want to send the api-key. (empty)
api-key-value Value of the API key that will be send while trying out the APIs. This can also be provided/overwritten from UI. (empty)
fetch-credentials Allowed: omit | same-origin | include enables passing credentials/cookies in cross domain calls, as defined in the Fetch standard, in CORS requests that are sent by the browser (empty)

Methods

Method Description
loadSpec() To programmatically load spec. The method takes
  • either a string containing the url of the specs
  • or a JSON object representing a valid spec
 Example
scrollTo(path) To programmatically scroll to a section (identified by combination method and path).
path should be provided in the format of {method}-{path} for instance you want to scrollTo GET /user/login you should provide the location as get-/user/login  |  Example
setHttpUserNameAndPassword(
  securitySchemeId,
  username,
  password
) 		To programmatically provide username and password. securitySchemeId should be a valid securityScheme which you have defined in the spec
setApiKey(
  securitySchemeId, token
) 		To programmatically provide api-key. securitySchemeId should be a valid securityScheme which you have defined in the spec
setApiServer(apiServerUrl) To programmatically set API Server. apiServerUrl should be a valid server url which you have defined in the spec
scrollTo(path) To programmatically provide username and password

Events

Below is an example on how to handle events using plain JS 
          
            <html>
            ...        
              <rapi-doc id="the-doc" spec-url = "https://.../spec.yaml"> </rapi-doc>

              <script>
                window.addEventListener('DOMContentLoaded', (event) => {
                  /* 
                    Ensure that the DOM is loaded, then add the event listener.
                    here we are listenig to 'before-try' event which fires when the user clicks 
                    on TRY, it then modifies the POST requests by adding a custom header 
                  */
                  const rapidocEl = document.getElementById('the-doc');
                  rapidocEl.addEventListener('before-try', (e) => {
                    if (e.detail.request.method === 'POST') {
                      e.detail.request.headers.append('custom-token', 'AAA.BBB.CCC');
                    }
                  });
                });
              </script>
            ...
            </html>
Event Description
before-render fired before rendering, provides spec object which can be modified and the changes will be reflected in rendering
spec-loaded fired after the spec is parsed, and rendered. Provides an object representing the spec.
before-try fired before user clicks try. Provides a request object that can be modified before making the final call to the API.
after-try fired after try (API-call) is completed and provides a request and response object In case of an error it will provide an request and err object Example
api-server-change fires when you change the API server

Slots

slots are predefined placeholders inside a RapiDoc component. You can use these slots to place your custom html in certain desired locations inside RapiDoc. Below is an example on how to inject HTML/CSS/JS at various locations in RapiDoc 
            
              <html>
                ...
                <rapi-doc spec-url = "https://petstore.swagger.io/v2/swagger.json">
                  <div> <!-- HTML Elements without slot attribute goes into default location-->
                    <h1> My HTML Heading  </h1>
                  </div>

                  <!-- provide slot attribute to place an element at desired location -->
                  <img slot="nav-logo" src="https://via.placeholder.com/100" style="width:50px; height:50px"/>
                 
                </rapi-doc>
                ...
              </html>
Slot Name Description
(default) any content placed inside <rapi-doc> tag, will be shown immediately under the header and above the info section
logo use this slot to replace the logo on the header
header contents appear at the header after the spec-url input
footer contents appear at the bottom of the spec
nav-logo contents appear at the top of Side navigation bar usually used for logo. (only available in read-mode)
overview contents appear at overview section - top of the document. You can link to this section using #overview
servers contents appear at server section which is under the overview slot. You can link to this section using #servers
auth contents appear at authentication section which is under the overview > servers slot. You can link to this section using #auth
operations-top contents appear at the top of all the operations but below overview > servers > auth section. Use this section to provide content that applies to all the operations. You can link this section using #operations-top
tag--{tag-name} each tag is identified by a name, this slot can be used to insert HTML content under various tags
{method}-{path} each path is identified by an id. which is in the format of {method}-{path}, and certain invalid characters such as {, }, #, space is replaced by hyphen (-). Use this slot to insert HTML content into a specifi tag
Example of Slots: All Slots  |  default and footer  |  nav-logo

Advanced Styling

For those who like to perform advanced styling by building RapiDoc from source
Developers can providing their own style overrides in src/styles/custom-styles.js. This is provided as a clean way into add custom style overrides without making changes to the codebase 
                  
                    // src/styles/custom-styles.js

                    import { css } from 'lit-element';
                    export default css`
                      .tag.title {
                        text-transform: capitalize;
                        border-left: 2px dotted var(--red);
                      }
                    `;
and build RapiDoc 
                  
                    npm run build
generated rapidoc-min.js in dist folder will have your styles

Supported vendor extensions

x-code-sample
x-codeSample 		Use this vendor-extension to provide code samples in various languages Usage Example
x-badges Use this vendor-extension to annotate end-points with short color coded lables Usage Example
x-tag-expanded Use this vendor-extension to expand or collapse paths under a tag (applies only in view and focused render-style) Usage Example
x-client-id
x-client-secret 		Use these vendor-extensions to pre fill client-id and client-secret in the UI Usage Example