Using OpenAPI

As an alternative to Smithy, you can use OpenAPI Version 3.0.3 to define your API.

To use OpenAPI, in TypeSafeApiProject, specify it as the model.language.

TSJAVAPYTHON

new TypeSafeApiProject({
  model: {
    language: ModelLanguage.OPENAPI,
    options: {
      openapi: {
        title: "MyApi"
      },
    },
  },
  ...
});

TypeSafeApiProject.Builder.create()
        .name("myapi")
        .model(ModelConfiguration.builder()
                .language(ModelLanguage.OPENAPI)
                .options(ModelOptions.builder()
                        .openapi(OpenApiModelOptions.builder()
                                .title("MyApi")
                                .build())
                .build())
        ...
        .build();

TypeSafeApiProject(
    model=ModelConfiguration(
        language=ModelLanguage.OPENAPI,
        options=ModelOptions(
            openapi=OpenApiModelOptions(
                title="MyApi"
            )
        )
    ),
    ...
)

Using the OpenAPI specification

Your model/src/main/openapi/main.yaml file defines your API using OpenAPI Version 3.0.3. For example,

openapi: 3.0.3
info:
  version: 1.0.0
  title: Example API
paths:
  /hello:
    get:
      operationId: sayHello
      x-handler:
        language: typescript
      parameters:
        - in: query
          name: name
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Successful response
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/HelloResponse"
components:
  schemas:
    HelloResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message

Splitting your model definition

You can divide your specification into multiple files using $ref.

For example, you can structure your spec as follows:

|_ model/src/main/openapi/
    |_ main.yaml
    |_ paths/
        |_ index.yaml
        |_ sayHello.yaml
    |_ schemas/
        |_ index.yaml
        |_ helloResponse.yaml

where main.yaml looks as follows:

openapi: 3.0.3
info:
  version: 1.0.0
  title: Example API
paths:
  $ref: "./paths/index.yaml"
components:
  schemas:
    $ref: "./schemas/index.yaml"

paths/index.yaml:

/hello:
  get:
    $ref: "./sayHello.yaml"

paths/sayHello.yaml:

operationId: sayHello
x-handler:
  language: typescript
parameters:
  - in: query
    name: name
    schema:
      type: string
    required: true
responses:
  "200":
    description: Successful response
    content:
      "application/json":
        schema:
          $ref: "../schemas/helloResponse.yaml"

schemas/index.yaml:

HelloResponse:
  $ref: "./helloResponse.yaml"

schemas/helloResponse.yaml:

type: object
properties:
  message:
    type: string
required:
  - message

---

Last update: 2024-05-08