OpenAPI/Swagger

The OpenAPI Specification (OAS) previously known as the Swagger Specification establishes a uniform, language-independent protocol for HTTP APIs. This protocol enables both humans and machines to explore and grasp the functionalities of a service without needing access to its source code or extensive documentation, or resorting to network traffic examination. With a well-defined OAS, users can effectively engage with the remote service with minimal implementation complexity.

An OpenAPI document represents a formal description of an API that tools can use to generate code, documentation, test cases, and more. Most programming languages and frameworks automatically generate OAS-based documentation from the application code. This makes the process much more efficient and eliminates the need to manually create and update documentation. Documentation generation tools analyze the application's structure and comments in the code and then convert this information into a readable and OAS-compliant format that describes functions, access paths, parameters, responses, and other relevant API elements.

Requirements

A document containing the OpenAPI/Swagger specification for the API is required. The document can be in JSON or YAML format. Dataedo supports the 2.0.X and 3.0.X versions of the specification. The document can be provided using: a link, a file on disk, or by pasting.

Import

Details on how to import OpenAPI documentation can be found at this link

Connector specification

Imported metadata

Supported Dataedo features

Supported OpenAPI features

Examples of supported OpenAPI Specification features:

• Documentation title and description,
• Server URLs,
• Endpoints paths and HTTP methods (operations),
• Endpoint/operation description,
• Request path, query, header and cookie parameters,
• Request parameters name, description, required flag, datatype, format and style,
• Request body fields name, title, description, required flag, datatype, format and default value,
• Response status codes and description,
• Response body fields name, title, description, required flag, datatype, format and default value,
• Response header parameters name, description, required flag, datatype, format and style,
• Data models polymorphism and mixed types (oneOf, anyOf schemas),
• Data models inheritance (allOf schemas),
• Nested data models (arrays and objects).

Unsupported OpenAPI features

Examples of unsupported (will not be imported) OpenAPI Specification features:

• Server URL formats and templating,
• Documentation version,
• Tags,
• External documentation,
• Media types (model is created using the first one),
• Deprecated and empty value flag,
• Additional properties,
• Enum and constant values,
• Example values,
• Parameter dependencies,
• Constraints on values (like min, max, pattern, etc.),
• Free form objects (properties without schema),
• Discriminators,
• Not schema,
• Authentication and security,
• Callbacks (webhooks).

Known limitations

It is not possible to run the import through CMD functionality or using Scheduler.

It is not possible to filter by endpoints path.