## OpenAPI spec loader URL: https://docs.atlan.com/platform/references/openapi-spec-loader > Import OpenAPI specifications from a URL or cloud storage into Atlan to catalog and govern APIs. Reference for workflow configuration, spec sources, and APISpec/APIPath mapping rules. # OpenAPI spec loader Imports OpenAPI specifications from URLs or cloud storage (S3, GCS, ADLS) and creates APISpec and APIPath assets in Atlan for cataloging and governance. This reference documents app configuration, specification-source options, how OpenAPI properties map to Atlan metadata, and APISpec/APIPath creation behavior. ## Access The OpenAPI spec loader app is disabled by default. To use this app, [**contact Atlan support**](https://docs.atlan.com/support/submit-request) and request it be added to your tenant. ## Configuration This section defines the fields required to configure the workflow and control how OpenAPI specifications are imported. ### Workflow name Specifies a unique and descriptive name to identify the workflow configuration in the Atlan interface. This name appears in the workflow list and helps distinguish it from other API-related workflows. *Example:* ```js atlan-openapi-spec-loader ``` ### Import spec from Defines how the workflow accesses the OpenAPI specification file. You can either provide a direct URL to the JSON or YAML file, or configure object storage to fetch the file from a cloud bucket. ### URL Use this option when your OpenAPI specification is available through a stable URL that Atlan can reach. This is typically the simplest approach for one-time or ad-hoc imports where the spec is already hosted on an internal or public endpoint. #### Specification URL Specifies the full, direct URL to the OpenAPI specification file you want the workflow to load. This URL must point to a **raw JSON or YAML** document that fully conforms to the OpenAPI 2.0 or 3.x specification. You can get this URL from your API provider or backend team, most internal services expose their OpenAPI specification at a known endpoint (for example, `/openapi.json` or `/swagger.yaml`). Valid examples of what the URL may return: - A JSON document (OpenAPI 3.0/3.1 or Swagger 2.0) - A YAML document (same versions) Valid top-level structure examples include: ``` openapi: 3.0.3 info: title: Customer API version: 1.0.0 paths: /customers: get: summary: Get customers ``` Or JSON: ``` { "openapi": "3.0.3", "info": { "title": "Customer API", "version": "1.0.0" }, "paths": { "/customers": { "get": { "summary": "Get customers" }}}} ``` URL Format Requirements: - Must be a direct URL to the file, for example one that ends with `.json`, `.yaml`, or `.yml` - Must be reachable from Atlan’s infrastructure: - Public HTTPS endpoint - Internal endpoint exposed via allowlisting - Expiring or signed file URLs - Must not require login via browser-based authentication. - Must not return a Swagger UI HTML page, only the raw file content. *Example:* ``` https://api.company.com/openapi/v3/spec.json ``` ### Object storage Use this option to fetch the OpenAPI JSON or YAML specification file from a cloud object store such as Amazon S3, Google Cloud Storage (GCS), or Azure Data Lake Storage (ADLS). Object storage is recommended for larger files, automated pipelines, or recurring imports where the spec file is generated and updated outside Atlan. It also provides a more reliable and scalable alternative when the file size or access pattern makes direct URLs less suitable. When you select Object storage, the workflow retrieves the OpenAPI specification from a specific path or object location within your storage system. The file must contain a valid OpenAPI document in JSON or YAML format, regardless of its storage location. You can typically get this file from the team or system that generates your API specifications, for example, an API gateway export, a CI/CD pipeline output, or a backend service that periodically emits an openapi.json or swagger.yaml file into your storage bucket. For detailed information on configuring storage credentials, access methods, and required fields for each provider, see the general **[Object storage configuration for apps](https://docs.atlan.com/llms/platform/packages/object-storage-configuration/llms.txt)** guide, which applies to S3, GCS, and ADLS-based imports. ### Connection setup Controls whether the workflow creates a new connection to host the APISpec and APIPath assets or reuses an existing connection. ### Create Use this option when you want the workflow to create a new connection in Atlan specifically for the OpenAPI specification and its API paths. ### Connection name Specifies the name of the new connection in Atlan. All assets created from the OpenAPI specification (the APISpec and APIPaths) are stored under this connection. *Example:* ```js Customer API (OpenAPI) ``` ### Connection admins Specifies one or more users or groups who are assigned as connection admins for the new connection. Connection admins can manage metadata, policies, and access control on the API assets created from the OpenAPI specification. *Example:* ```js atlan-api-admins,platform-team ``` ### Reuse Use this option when you already have a connection that represents the system owning the APIs described by the OpenAPI specification, and you want to attach the APISpec and APIPath assets to that existing connection. ### Connection Specifies the existing connection in Atlan that hosts the APISpec and APIPath assets created from the OpenAPI specification. - Use the dropdown to select a connection that already exists in your workspace. - The workflow never creates or alters the underlying connection; it only adds API assets to it. *Example:* ```js Snowflake - Customer APIs ``` ## Generated assets This section describes how the workflow creates and populates assets in Atlan after the OpenAPI specification has been loaded. If you choose to create a new connection during setup, the workflow creates that connection (with the specified connection admins). If you choose to reuse an existing connection, the workflow attaches the APISpec and APIPath assets to that existing connection. ### APISpec A single **APISpec** asset is created to represent the entire JSON or YAML specification file provided in the setup. The APISpec asset is created within the connection being reused or the new connection created by the workflow. The following properties are populated on the APISpec asset when present in the OpenAPI JSON or YAML: | Attribute | Atlan UI | Source in JSON/YAML | |-----------------------------|------------------|-------------------------| | `name` | Name | `info.title` | | `description` | Description | `info.description` | | `apiSpecType` | Spec type | `openapi` | | `apiSpecTermsOfServiceURL` | Terms of Service | `info.termsOfService` | | `apiSpecContactEmail` | N/A | `info.contact.email` | | `apiSpecContactName` | N/A | `info.contact.name` | | `apiSpecContactURL` | N/A | `info.contact.url` | | `apiSpecLicenseName` | N/A | `info.license.name` | | `apiSpecLicenseURL` | License | `info.license.url` | | `sourceURL` | View in API | URL of JSON/YAML file | | `apiSpecVersion` | N/A | `info.version` | | `apiExternalDoc.url` | N/A | `externalDocs.url` | | `apiExternalDoc.description`| External docs | `externalDocs.description` | #### APISpec field details - **`name`**: Display name for the API specification in Atlan, taken from the OpenAPI `info.title`. - **`description`**: Long-form description of the API specification, shown in the asset sidebar, from `info.description`. - **`apiSpecType`**: Type of API specification represented by the asset. For this app, the value is always set to `openapi`. - **`apiSpecTermsOfServiceURL`**: Link to the API terms of service, from `info.termsOfService`. - **`apiSpecContactEmail`**: Contact email address for questions about the API, from `info.contact.email`. - **`apiSpecContactName`**: Name of the contact person or team for the API, from `info.contact.name`. - **`apiSpecContactURL`**: URL for the contact or support page for the API, from `info.contact.url`. - **`apiSpecLicenseName`**: Name of the license that governs use of the API, from `info.license.name`. - **`apiSpecLicenseURL`**: Link to the full text of the API license from `info.license.url`. - **`sourceURL`**: URL of the OpenAPI JSON or YAML file used to create the APISpec asset. It appears as the **View in API** button in Atlan. - **`apiSpecVersion`**: Version string of the API specification, from `info.version`. - **`apiExternalDoc.url`**: URL for additional external documentation about the API, from `externalDocs.url`. - **`apiExternalDoc.description`**: Short description of the external documentation link, from `externalDocs.description`. ### APIPaths One **APIPath** asset is created for each unique path defined under `paths` in the OpenAPI specification. Each APIPath is populated with the following properties when present in the JSON or YAML: | Attribute | Atlan UI | Source in JSON/YAML | |-----------------------------|---------------|--------------------------------------------------------------------------------------| | `name` | Name | `paths[].{url}` | | `description` | Description | A markdown table composed of `paths[].{operation}` and `paths[].{operation}.summary` | | `apiPathRawURI` | Raw URI | `paths[].{url}` | | `apiPathSummary` | N/A | `paths[].summary` | | `apiPathAvailableOperations`| Methods | `paths[].{operation}` | | `apiPathIsTemplated` | Is templated? | `true` if `paths[].{url}` contains `{` and `}`, otherwise `false` | #### APIPath field details - **`name`**: Display name for the API path in Atlan. By default, this is the raw path string from the OpenAPI spec, for example `/customers/{id}`. - **`description`**: Markdown description that summarises the operations on this path, built from each operation and its `summary`. - **`apiPathRawURI`**: Exact path URI string as defined in the OpenAPI spec under `paths`, for example `/orders` or `/orders/{orderId}`. - **`apiPathSummary`**: Short free-text summary of the path, when provided in the specification, for example "Operations on customer resources." - **`apiPathAvailableOperations`**: List of HTTP methods supported on this path, for example `GET`, `POST`, or `DELETE`. - **`apiPathIsTemplated`**: Boolean flag that indicates whether the path contains template variables. The value is `true` when the path includes `{}` placeholders, for example `/customers/{id}`, and `false` otherwise. ## See also - [Atlan's OpenAPI](https://docs.atlan.com/llms/platform/get-started/atlan-s-open-api/llms.txt) - [API authentication](https://docs.atlan.com/llms/platform/get-started/api-authentication/llms.txt) ---