Comprehensive Guide to Exporting Swagger Definition Files: From UI to API Documentation

Visible Links in Swagger UI for API Definitions

In the top bar or below the API title in Swagger UI, the URL of the API definition file is often displayed. For instance, in the described scenario, the URL appears as /v2/api-docs?group=full-petstore-api, with the full path being http://localhost:8080/v2/api-docs?group=full-petstore-api. Users can right-click this link and select "Save As" to download the swagger.json or swagger.yaml file. This approach is effective for newer Swagger UI versions with intact interface elements.

Inspecting Page Source to Locate URL Parameters

If no direct download link is visible in Swagger UI, examine the HTML page source to find the API definition file's URL. Search for the url parameter, typically within the SwaggerUIBundle configuration object. For example:

const ui = SwaggerUIBundle({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  // other configuration parameters
});

The url value here is the direct address of the API definition file. If url is a JavaScript expression, further analysis may be needed to determine its resolved value.

Using Browser Developer Tools to Monitor Network Requests

Another reliable method involves using the browser's developer tools. Open the "Network" tab, disable caching, and refresh the Swagger UI page. In the list of HTTP requests, filter by XHR type to find files named swagger.json, swagger.yaml, api-docs, or similar. Once identified, copy the URL from the request details or download the response content directly.

Retrieving Configuration Information via Browser Console

For different Swagger UI versions, execute specific JavaScript commands in the browser console to obtain the API definition file's URL:

• Swagger UI 3.x: Run ui.getConfigs().url to return the URL from the configuration.
• Swagger UI 2.x: Run swaggerUi.api.url to get the address of the API definition file.

These commands directly access the configuration properties of the Swagger UI instance, ensuring accurate URL retrieval.

Handling Embedded API Definition Files

In some cases, the OpenAPI definition might be embedded within a JavaScript file. Locate the relevant .js file, extract the JSON or YAML definition content, and remove surrounding JavaScript code. For example, if the definition is wrapped in a variable assignment, retain only the JSON portion.

Summary and Best Practices

Multiple methods exist for exporting Swagger definition files; choose the appropriate one based on the specific environment. Prioritize visible link downloads, and if unavailable, proceed with source inspection, network monitoring, and console commands. Ensure the final file adheres to OpenAPI specifications for effective API documentation management and code generation.