Using OpenAPI
As an alternative to Smithy or TypeSpec, you can use OpenAPI Version 3.0.3 to define your API.
To use OpenAPI, in TypeSafeApiProject
, specify it as the model.language
.
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-10-30