Skip to main content

APIs

Use apis to sync repository-owned API specification files as API groups in UiGraph.

Supported API types​

  • openapi
  • graphql
  • grpc

Minimal config​

apis:
  - name: booking-openapi
    type: openapi
    path: ./specs/openapi.yaml

Each entry requires:

  • name
  • type
  • path

What the CLI does​

For each API entry, the CLI:

  1. validates the type
  2. checks that path exists
  3. reads the spec file as raw content
  4. sends the API group metadata and file content to the gateway

If a file does not exist, validation fails before sync.

Multiple APIs example​

apis:
  - name: rest-api
    type: openapi
    path: ./specs/openapi.yaml

  - name: graphql-api
    type: graphql
    path: ./specs/schema.graphql

  - name: grpc-api
    type: grpc
    path: ./specs/service.proto

OpenAPI and test linkage​

If you want API test cases to link to a specific operation, include:

  • apiGroupName in the test case
  • operationId in the test case
  • matching operationId values in the OpenAPI document

Example:

apis:
  - name: storefront-api
    type: openapi
    path: ./.uigraph/openapi/storefront-sample.yaml

testPacks:
  - name: auth-smoke
    type: smoke
    testCases:
      - type: api
        title: Login returns 200
        order: 1
        apiGroupName: storefront-api
        operationId: loginUser
        expectedStatusCode: 200

Path tips​

  • Use repository-relative paths in .uigraph.yaml.
  • Keep API specs versioned with code.
  • Prefer stable file locations to reduce CI failures.
  • keep one API group name stable per spec file
  • store OpenAPI, GraphQL, and gRPC artifacts next to the code they document
  • add operationId values to OpenAPI specs when you want downstream test-case linking
  • use dry-run in CI to catch missing file paths early