Lazy Loading
This information applies to SwaggerHub SaaS and SwaggerHub On-Premise 1.20.0 and later.
SwaggerHub OpenAPI Editor and interactive API documentation use a technique called lazy loading to optimize loading of external $ref references, such as domain references. With lazy loading, external $refs are resolved and loaded only when they are needed to display a specific operation.
Enable or disable lazy loading (SwaggerHub On-Premise)
In SwaggerHub On-Premise, lazy loading is disabled by default, but the administrator can enable it if needed.
Open the Admin Center.
Select Settings on the left.
Select or unselect Enable Lazy Loading.
Click Save Changes and Restart. Wait a few minutes for the system to restart completely.
How lazy loading works
API documentation is initially displayed with collapsed entries. The initial render processes only the API definition, so that the API page loads fast. The referenced domains will be loaded later as the user expands operations that contain domain references. Note that operation expansion will load only the domains required to display that specific operation. Some domains might not be loaded at all if the corresponding operations are not expanded in the docs. This helps reduce the API documentation load time and improve the performance, which is especially useful for large APIs with many domain references.
Validation
Lazy loading affects the way validation errors are reported in the editor. By default, the editor analyzes just the current definition, but not the referenced domains. Domain errors will surface in the editor only after these domains are lazy loaded. Keep this in mind when validating your APIs and domains.
This means you may not see any errors in the editor initially:
 |
Click the image to enlarge it.
but errors will appear as you expand operations in the interactive documentation:
 |
Click the image to enlarge it.
Once a domain is lazy loaded, it will not be loaded again, and any errors found in that domain will remain in the API’s error list. To pick up domain changes, you need to refresh the API page in the browser and expand the operations that would trigger the loading of that domain.
Troubleshooting
Validate the whole API
As a quick validation check, try to download the resolved API definition by using the Export > Download API > Resolved YAML command in the editor. If the command succeeds, it means the API and the referenced domains are valid.
If you see an error like the one below, it means there is a syntax error somewhere in the API or in the referenced domains.
However, this method only tells you if there are errors, but it does not tell you where those errors are. To see which domains contain errors, use the method described below.
Find and fix errors
To see a full list of errors and domains containing those errors, expand everything in the interactive documentation to trigger domain validation.
Open the API in the editor.
If the UI panel is hidden, click
View UI Documentation in the sidebar on the left to show it.Expand all the operations one by one, and observe the validation status in the editor.
If the operation expansion triggers an error:
Click in the operation info to jump to the YAML code.
Find domain references in the operation definition.
$ref: 'https://api.swaggerhub.com/domains/...'
Jump to those domains.
Click the image to enlarge it.
See if the domain has syntax errors and fix the errors. Make sure to save the changes.
If a domain contains references to other domains, use the same approach (doc expansion) to validate the other domains too.
Go back to the API and refresh the page in the browser. Expand the problematic operation again to fetch the updated domain and make sure there are no validation errors this time.
Continue expanding other operations until you verify all of them.
If you need help with syntax validation, ask the community, use the in-app support chat, or open a support ticket.
Performance tips for internal $refs
Lazy loading gives a performance boost for external $refs only, but it does not affect internal $refs ($ref: '#/...'). If you have an API with many internal $refs, and it loads slowly, we suggest that you move the referenced definitions to a domain and replace the internal $refs with domain references. Lazy loading will then come into play to load the API more effectively.