Using OpenApi to describe your services

Orbital can use OpenApi specs to understand what APIs exist, and how to call them.

Orbital 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.

​Adding 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 behaviour.

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 behaviour for create is different between response models and attribute types:

​Describing response types

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

Assigning Taxi type names to models

You can optionally define a custom type name for response types being published to Orbital. 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:

Adding type annotations to attributes

Enrich attributes with semantic type metadata

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:

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

​Describing 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

​Publishing OpenAPI specs to Orbital

Once you have added taxi annotations to your OpenApi spec, you’re ready to publish it to Orbital.

​Different ways to publish OpenAPI specs

There are a few different ways to expose your OpenAPI spec to Orbital, each which suits different team workflows.

​Combining OpenAPI and Taxi in a single project

You can configure your Taxi project to read OpenAPI specs directly by defining their location in the additionalSources section of your taxi.conf file.

Example directory structure:

.├── src/           # Taxi files├── openapi/       # OpenAPI specs└── taxi.conf

Configure in your taxi.conf:

name: com.example/my-taxi-projectversion: 0.2.0sourceRoot: src/additionalSources: {  "@orbital/openapi" : "openapi/*.yaml"}

OpenAPI-specific configuration

You can optionally provide additional metadata for your OpenAPI spec by creating a .taxi.conf file with the same name as your spec.

If no config file is provided, Orbital will use the project’s organization as the default namespace.

Example file structure:

openapi/├── petflix-api-spec.yaml       # Your OpenAPI spec└── petflix-api-spec.taxi.conf  # Optional configuration file

Configuration file contents:

defaultNamespace: "com.petflix.pets"serviceBasePath: "https://petflix.com"

​Guide: Importing OpenAPI specs via the UI

The project you import into needs to be editable, so Orbital can write the spec into it. Projects created in the UI are; for a project pulled from git or read from disk, enable editing when adding it.

• Open Data sources in the sidebar, and click Add data source (or go straight to http://localhost:9022/default/default/data-source-manager/add)
• Select the project to add the data source to, then choose OpenAPI from the data source dropdown

Importing an OpenAPI spec from a URL. The spec itself is added to the project by default

• Either upload the OpenAPI spec file directly (File), or enter a URL to load the spec from (Url)
• Provide a default namespace (eg: com.petflix.pets). Services and types from your OpenAPI spec are created in this namespace
• If your OpenAPI spec doesn’t define a base url (ie., servers/url), then specify a Base Url. All paths in the OpenAPI spec are treated as relative to this
• Choose how to store it:
  • Add the OpenAPI spec to your project (recommended) - the spec is saved as-is in the project’s openapi/ directory, alongside a small .taxi.conf holding the namespace (see combining OpenAPI and Taxi in a single project). The spec stays the source of truth, and Orbital derives Taxi from it whenever the project loads, so updating the API is just replacing the file. Types you link in the next step are written back into the spec as x-taxi-type annotations
  • Convert the OpenAPI spec to Taxi - generates Taxi from the spec and stores the Taxi instead. The spec isn’t kept, so later changes are made in Taxi. Use this when you want to hand-edit the result
• Then click Configure

Preview your imported schema

Orbital shows what it read from the spec - the models, types, services and operations - so you can check everything looks correct, and link types to the shared types already in your catalog before saving. Select a model in the tree on the left to see its attributes; the diagram on the right shows how the services and models relate.

The preview of an imported spec, with the Review model selected

Any types defined with create: true within the spec appear within the Types section.

Services and operations should have 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 - for example, swapping a newly created type for a shared one from your catalog. Once you’re happy, click Add to project, and the OpenAPI spec is imported.