Use OpenAPI to describe your services

Flow can use OpenAPI specs to understand what APIs exist, and how to call them.

Flow uses Semantic schemas to describe how data relates between systems. For OpenAPI, this means enriching return types and input parameters with metadata to describe them semantically.

To do this, we embed Taxi metadata within the OpenAPI specs.

Add Taxi annotations to OpenAPI specs

Taxi annotations use a custom x-taxi-type block within OpenAPI specs.

Example:

x-taxi-type:
  # The name of the type
  name: com.acme.MyType
  # Optional.  Indicates if the type should be created if not already present.
  create: false

The create element is optional, and overrides the default behavior.

If create is set to false, then schemas which attempt to publish types that aren’t already defined on the schema server are rejected as compilation errors.

This is to prevent accidental typos.

However, the default behavior for create is different between response models and attribute types:

Entity type Default create behavior Impact

Model (Response type)

true

By default, if the model isn’t already present within the schema, it’s created

Attribute

false

By default, if an attribute type isn’t already present within the remote schema, then the OpenAPI spec is rejected

Describe response types

Response models returned from API calls can be enriched to include semantic metadata.

Assign Taxi type names to models

You can optionally define a custom type name for response types being published to Flow. If omitted, then the type name is inferred from the rest of the schema.

components:
  schemas:
    Pet:
      # Assign a Taxi type name to the model.
      # Optional
      x-taxi-type:
        name: petstore.Pet
      # Everything else is standard OpenAPI spec...
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - required:

Add type annotations to attributes

Enrich attributes with semantic type metadata

components:
  schemas:
    NewPet:
      required:
        - name
      properties:
        name:
          x-taxi-type:
            name: petstore.Name
          type: string
        tag:
          x-taxi-type:
            name: petstore.Tag
          type: string

By default, it’s expected that types referred to in x-taxi-type within attributes have already been defined on the schema server, as part of your core taxonomy.

However, if you are intentionally publishing new types from your OpenAPI spec, then set create to true:

 components:
  schemas:
    NewPet:
      required:
        - name
      properties:
        name:
          x-taxi-type:
            name: petstore.Name
            # petstore.Name will be created if not present
            create: true
          type: string

Describe service parameters

Inputs into services can also be enriched, to annotate the semantic data required.

Simply add a x-taxi-type annotation to each input, containing a name attribute with a reference to the name of the type from your core taxonomy.

  ## ... OpenApi spec trimmed...
  paths:
    /pets/{id}:
      get:
        description: Returns a user based on a single ID, if the user does not have access to the pet
        operationId: find pet by id
        parameters:
          - name: id
            in: path
            description: ID of pet to fetch
            required: true
            schema:
              type: integer
              format: int64
             x-taxi-type:
               name: petstore.PetId  # <-- Name of type from core taxonomy

Publish OpenAPI specs to Flow

Once you have added Taxi annotations to your OpenAPI spec, you’re ready to publish it to Flow.

Before you can import an OpenAPI spec into Flow, ensure you have configured an editable Schema source - either a local disk repository or a Git repository. Be sure to enable editing of the repository when adding it. This lets Flow store the converted OpenAPI spec, with some additional metadata that it creates when importing.

Import through the UI

  • Choose Data Sources in the left navigation bar, then Add data source.

  • Select a project to import into, then choose Swagger / OpenAPI from the data source dropdown list.

select open api flow

  • Either provide the OpenAPI spec file directly, or enter a URL to load the spec from

  • Provide a default namespace. (eg: com.petflix.pets). Services from your OpenAPI spec are imported into this namespace

  • If your OpenAPI spec doesn’t define a base URL (ie.,: servers/url), then specify one. All paths in the OpenAPI spec are treated as relative to this path

  • Click Configure

Preview your imported schema

open api preview

Your imported OpenAPI spec will be available for you to browse, to make sure everything looks correct.

Any types that have been defined as create: true within the Yaml spec should appear within the Types section.

Services and operations should’ve been created for all endpoints within your OpenAPI spec.

At this point, you can edit types (by clicking on the pencil icon next to the type name) to further refine your schema. Once you’re happy, click Save and the OpenAPI spec will be imported.

lifebuoy

Help and support