diff --git a/openapi/frameworks/elysia.mdx b/openapi/frameworks/elysia.mdx index 295066af..f9e5d98d 100644 --- a/openapi/frameworks/elysia.mdx +++ b/openapi/frameworks/elysia.mdx @@ -126,7 +126,7 @@ This keeps resources isolated by domain (`stations`, `trips`, `bookings`) and ma Open `http://localhost:3000/openapi/json` to view the OpenAPI document in JSON format: ```yaml -openapi: 3.0.3 +openapi: 3.1.2 info: "title": "Train Travel API", "description": "API for finding and booking train trips across Europe.", @@ -181,6 +181,7 @@ const app = new Elysia() .use( // !mark(2:12) openapi({ + openapiVersion: "3.1.2", documentation: { info: { title: "Train Travel API", @@ -231,7 +232,7 @@ const app = new Elysia() .listen(3000); ``` -This configures the [root document object](https://spec.openapis.org/oas/v3.0.3.html#openapi-object) of the OpenAPI document. +This configures the [root document object](https://spec.openapis.org/oas/v3.1.2.html#openapi-object) of the OpenAPI document. The `info` object is a required property used to add metadata about the API. The `externalDocs` object lets you extend your documentation by referencing an external resource. @@ -241,9 +242,9 @@ The `operationId` is the identifier for an operation. It is case sensitive and m ## OpenAPI Specification versions supported by Elysia and Speakeasy -Speakeasy currently supports the OpenAPI Specification versions 3.0 to 3.2. The recommendation is to use at least version 3.1, as it's fully compatible with [JSON Schema](https://json-schema.org/), which gives you access to a [large ecosystem of tools and libraries](https://json-schema.org/tools). +Speakeasy currently supports the OpenAPI Specification versions 3.0 to 3.2. The recommendation is to use at least version **3.1**, as it's fully compatible with [JSON Schema](https://json-schema.org/), which gives you access to a [large ecosystem of tools and libraries](https://json-schema.org/tools). -The guide uses OpenAPI v3.0.3 as it is the latest version Elysia supports at time of writing, although we have sent them a pull request to get them to v3.1. 🤞 +The guide uses OpenAPI v3.1.2, which Elysia supports through the `openapiVersion` option. OpenAPI 3.1 is fully compatible with JSON Schema, giving you access to a large ecosystem of tools and libraries. To check which version you are using, open `http://localhost:3000/openapi/json` and see the OpenAPI Specification version in the root document object. @@ -277,7 +278,7 @@ export const createBookingRequestSchema = t.Object( ``` -The Elysia schema builder, `t`, gives compile-time and runtime type safety. It also registers the model as a reusable OpenAPI [Components Object](https://spec.openapis.org/oas/v3.0.3.html#components-object) schema, which you can see at the bottom of your OpenAPI document: +The Elysia schema builder, `t`, gives compile-time and runtime type safety. It also registers the model as a reusable OpenAPI [Components Object](https://spec.openapis.org/oas/v3.1.2.html#components-object) schema, which you can see at the bottom of your OpenAPI document: ```yaml components: @@ -342,7 +343,7 @@ If you look at your OpenAPI document now, you'll see that the `content` of the P ## Adding extra information to a route using the detail field -The [`detail`](https://elysiajs.com/plugins/openapi.html#detail) field is used to define a route for the OpenAPI document. It extends the [OpenAPI Operation Object](https://spec.openapis.org/oas/v3.0.3.html#operation-object), which describes an API operation within a path. +The [`detail`](https://elysiajs.com/plugins/openapi.html#detail) field is used to define a route for the OpenAPI document. It extends the [OpenAPI Operation Object](https://spec.openapis.org/oas/v3.1.2.html#operation-object), which describes an API operation within a path. Add the following `detail` field to the hook object of the `post()` route: @@ -383,7 +384,7 @@ responses: { }, ``` -The [Responses Object](https://spec.openapis.org/oas/v3.0.3.html#responses-object) lists possible outcomes for the POST request. The success response includes a [`schema`](https://spec.openapis.org/oas/v3.0.3.html#schema-object) that describes the returned booking payload. The schema can be referenced with [`$ref`](https://spec.openapis.org/oas/v3.0.3.html#reference-object). +The [Responses Object](https://spec.openapis.org/oas/v3.1.2.html#responses-object) lists possible outcomes for the POST request. The success response includes a [`schema`](https://spec.openapis.org/oas/v3.1.2.html#schema-object) that describes the returned booking payload. The schema can be referenced with [`$ref`](https://spec.openapis.org/oas/v3.1.2.html#reference-object). Add the booking schema in `src/train/schemas.ts`: @@ -507,7 +508,7 @@ Add the following `tags` array to the configuration object of the `openapi` plug ) ``` -This adds a `tags` array to the root OpenAPI document object. In the above code, we add metadata to the tag by passing in a [Tag Object](https://spec.openapis.org/oas/v3.0.3.html#tag-object) (instead of a string) to the tag array item. +This adds a `tags` array to the root OpenAPI document object. In the above code, we add metadata to the tag by passing in a [Tag Object](https://spec.openapis.org/oas/v3.1.2.html#tag-object) (instead of a string) to the tag array item. After adding tags to your routes, you'll see that they are organized by tags in Scalar: