OpenAPI spec loader

App

The OpenAPI spec loader app crawls API definitions from an OpenAPI JSON or YAML specification and creates corresponding APISpec and APIPath assets in Atlan. It automatically ingests your API contract, maps key metadata, and structures it into searchable, governed API assets, making your APIs discoverable and easier to manage within Atlan.

Use this reference to understand each configuration field in the workflow and how the app populates APISpec and APIPath metadata from your specification.

Access

The OpenAPI spec loader app is disabled by default. To use this app, contact Atlan support 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:

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 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:

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:

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:

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
• API authentication