OpenAPI/Swagger

Hubert Książek - Dataedo Team Hubert Książek 3rd June, 2024

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.

Sample Swagger document

Import

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

Result of import

Connector specification

Imported metadata

Imported Editable
Endpoints & HTTP methods
  Description
  Header, Path, Query, Cookie parameters
    Name
    Description
    Nullability
    Datatype & Format
  Request body
    Field name
    Title
    Description
    Nullability
    Datatype & Format
    Default value
  Status codes
    Code
    Description
    Response body
      Field name
      Title
      Description
      Nullability
      Datatype & Format
      Default value
    Header parameters
    Name
    Description
    Nullability
    Datatype & Format

Supported Dataedo features

Feature Supported
Data profiling
Data classification
Data lineage (manual)
Reference data (import lookups)
Importing from DDL
Generating DDL
FK relationship tester

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.

Found issue with this article? Comment below
Comments are only visible when the visitor has consented to statistics cookies. To see and add comments please accept statistics cookies.
0
There are no comments. Click here to write the first comment.