DEV Community: Tatiana Caciur

Create Production-Ready SDKs With gRPC Gateway

Tatiana Caciur — Fri, 08 Dec 2023 17:52:24 +0000

You may want to provide a RESTful API in addition to your gRPC service without the need to duplicate your code.

gRPC Gateway is a popular tool for generating RESTful APIs from gRPC service definitions.

In this tutorial, we'll take a detailed look at how to use gRPC Gateway to generate an OpenAPI schema based on a Protocol Buffers (protobuf) gRPC service definition. Then we'll use Speakeasy to read our generated OpenAPI schema and create a production-ready SDK.

If you want to follow along, you can use the gRPC Speakeasy Bar example repository.

An Overview of gRPC Gateway

gRPC Gateway is a protoc plugin that reads gRPC service definitions and generates a reverse proxy server that translates a RESTful JSON API into gRPC.

This way, you can expose an HTTP endpoint that can be called by clients that don't support gRPC. The generated server code will forward incoming JSON requests to your gRPC server and translate the responses to JSON.

gRPC Gateway also generates an OpenAPI schema that describes your API. You can use this schema to create SDKs for your API.

OpenAPI Versions

gRPC Gateway outputs OpenAPI 2.0, and Speakeasy supports OpenAPI 3.0 and 3.1. To generate an OpenAPI 3.0 or 3.1 schema, you'll need to convert the OpenAPI 2.0 schema to at least OpenAPI 3.0.

The Protobuf to REST SDK Pipeline

To generate a REST API with a developer-friendly SDK, we'll follow these three core steps:

gRPC to OpenAPI: First, we will use gRPC Gateway to produce an OpenAPI schema based on our protobuf service definition. This generated schema is in OpenAPI 2.0 format.
OpenAPI 2.0 to OpenAPI 3.x: Next, as gRPC Gateway's output schema is in OpenAPI 2.0 and we need at least OpenAPI 3.0 for our SDK, we will convert the generated schema from OpenAPI 2.0 to OpenAPI 3.0.
OpenAPI 3.x to SDK: Finally, once we have the OpenAPI 3.0 schema, we will leverage Speakeasy to create our SDK based on the OpenAPI 3.0 schema derived from the previous steps.

By following these steps, we can ensure we have a robust, production-ready SDK that adheres to our API's specifications.

Step-by-Step Tutorial: From Protobuf to OpenAPI to an SDK

Now let's walk through generating an OpenAPI schema and SDK for our Speakeasy Bar gRPC service.

Check Out the Example Repository

If you would like to follow along, start by cloning the example repository:

git clone git@github.com:speakeasy-api/speakeasy-grpc-gateway-example.git
cd speakeasy-grpc-gateway-example

Install Go

To generate an OpenAPI schema from a protobuf file, we'll need to install Go and protoc.

This tutorial was written using Go 1.21.4.

On macOS, install Go by running:

brew install go

Alternatively, follow the Go installation instructions for your platform.

Install Buf

We'll use the Buf CLI as an alternative to protoc so that we can save our generation configuration as YAML. Buf is compatible with protoc plugins.

On macOS, install Buf by running:

brew install bufbuild/buf/buf

Alternatively, follow the Buf CLI installation instructions for your platform.

Install Buf Modules

We'll use Buf modules to manage our dependencies.

cd proto
buf mod update
cd ..

Install protoc-gen-go

Buf requires the protoc-gen-go plugin to generate Go code from protobuf files.

Install protoc-gen-go by running:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

Make sure that the protoc-gen-go binary is in your $PATH. On macOS, you can achieve that by running the following command if the go/bin directory is not already in your path.

export PATH=${PATH}:`go env GOPATH`/bin

Install Go Requirements

go mod tidy
go install \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
    google.golang.org/protobuf/cmd/protoc-gen-go \
    google.golang.org/grpc/cmd/protoc-gen-go-grpc

Generate the Go Code

We'll use Buf to generate the Go code from the protobuf file.

Run the following in the terminal:

buf generate

Buf reads the configuration in buf.gen.yaml, then generates the Go code in the proto directory.

This will generate the proto/speakeasy/v1/speakeasy.pb.go, proto/speakeasy/v1/speakeasy_grpc.pb.go, and proto/speakeasy/v1/speakeasy.pb.gw.go files.

Generate the OpenAPI Schema

Because we have the openapiv2 protoc plugin configured in our buf.gen.yaml file, Buf will generate an OpenAPI schema and save it as openapi/speakeasy/v1/speakeasy.swagger.json.

This is the OpenAPI 2.0 schema that gRPC Gateway generates by default.

Convert the OpenAPI Schema to OpenAPI 3.0

We'll use the excellent kin-openapi Go library to convert the OpenAPI 2.0 schema to OpenAPI 3.0.

In convert/convert.go, we use kin-openapi to unmarshal openapi/speakeasy/v1/speakeasy.swagger.json, then convert it to OpenAPI 3.0, then marshal it back to JSON, and finally write it to openapi/speakeasy/v1/speakeasy.openapi.json.

To do the conversion, run the following in the terminal:

go run convert/convert.go

Create an SDK With Speakeasy

Now that we have an OpenAPI 3.0 schema, we can create an SDK with Speakeasy.

We'll use the speakeasy generate command to create an SDK for the Speakeasy Bar gRPC service.

Run the following in the terminal:

speakeasy generate sdk \
    --schema openapi/speakeasy/v1/speakeasy.openapi.json \
    --lang typescript \
    --out ./sdk

This will create a TypeScript SDK in the sdk directory.

How To Customize the SDK

By modifying the protobuf service definition, we can customize the SDK via the generated OpenAPI schema.

We'll start with a basic example and add options to enhance the SDK.

Meet the Speakeasy Bar Protobuf Service

We'll start by taking a look at the Speakeasy Bar protobuf service definition in proto/speakeasy/v1/speakeasy.proto.

// from ./grpc-assets/speakeasy-raw.proto

The service defines one object type, called Drink.

// from ./grpc-assets/speakeasy-raw.proto

A service called SpeakeasyService has two methods, GetDrink and ListDrinks.

// from ./grpc-assets/speakeasy-raw.proto

Add API Information to the Service

We'll add information about the API to the service definition using options.openapiv2_swagger from grpc.gateway.protoc_gen_openapiv2.

// from ./grpc-assets/speakeasy.proto

We'll add a title, description, and version to the API.

This appears in the info object in the generated OpenAPI schema.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Speakeasy requires a servers object in the OpenAPI schema. We'll add a server to the API using the host key.

Our conversion script will add the servers object to the generated OpenAPI schema.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Add Descriptions and Examples to Components

To create an SDK that offers great developer experience, we recommend adding descriptions and examples to all fields in OpenAPI components.

Speakeasy will create documentation and usage examples based on the descriptions and examples we added.

We'll start with the Drink object type.

// from ./grpc-assets/speakeasy.proto

We added a title, description, and example to the Drink object type.

Note that the example is a stringified JSON object.

// from ./grpc-assets/speakeasy.proto

We use openapiv2_field to add options to the fields in the Drink object type.

For example, we added a description, pattern, format, and example to the productCode field.

This description and example will appear in the generated OpenAPI document.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

When Speakeasy creates an SDK, this description and example will appear in the generated documentation and usage examples.

This usage example is from the TypeScript SDK's documentation.

Note how the productCode field is represented by our UUID example instead of a random string.

import { SDK } from "openapi";

(async() => {
  const sdk = new SDK();

  const res = await sdk.drinks.getDrink({
    productCode: "602a7da9-b8bb-46e6-b288-457b561029b8",
  });

  if (res.statusCode == 200) {
    // handle response
  }
})();

Customize the OperationId

Speakeasy uses the operationId for each operation in the OpenAPI document to create method names in the SDK. By default, the operationId is the method name in the protobuf service definition.

We can customize the operationId for each method using options.openapiv2_operation.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Add Descriptions and Tags to Methods

Speakeasy uses the description and tags in the OpenAPI document to create documentation for each method in the SDK and group methods in the SDK.

We can add descriptions and tags to methods using options.openapiv2_operation.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Add OpenAPI Extensions

gRPC Gateway allows us to add OpenAPI extensions to the OpenAPI schema using the extensions key in our protobuf service definition.

For example, we can add the Speakeasy retries extension x-speakeasy-retries, which will cause the SDK to retry failed requests.

In the code example, we added the x-speakeasy-retries extension to the GetDrink method.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Add Tag Descriptions

Speakeasy uses each tag's description in the OpenAPI document to create documentation in the SDK.

We can add descriptions to tags in the protobuf definition by using options.openapiv2_swagger.

In the code example, we added a description to the drinks tag.

// from ./grpc-assets/speakeasy.proto

// from ./grpc-assets/speakeasy.openapi.json

Example Protobuf Definition and SDK Generator

The source code for our complete example is available in the gRPC Speakeasy Bar example repository.

The repository contains a TypeScript SDK and instructions on how to create more SDKs.

You can clone this repository to test how changes to the protobuf definition result in changes to the SDK.

After modifying your protobuf definition, you can run the following in the terminal to create a new SDK:

buf generate && go run convert/convert.go && speakeasy generate sdk \
    --schema openapi/speakeasy/v1/speakeasy.openapi.json \
    --lang typescript \
    --out ./sdk

Happy generating!

Create Production-Ready SDKs for tRPC

Tatiana Caciur — Fri, 01 Dec 2023 12:38:42 +0000

This tutorial will show you how to create an SDK for an API built with tRPC.

We'll explore how to generate an OpenAPI document for our tRPC API, and then we'll use this document to create an SDK using Speakeasy.

Here's what we'll cover:

Adding trpc-openapi to a tRPC project.
Generating an OpenAPI specification using trpc-openapi.
Improving the generated OpenAPI specification for better downstream SDK generation.
Using the Speakeasy CLI to create an SDK based on the generated OpenAPI specification.
Using the Speakeasy OpenAPI extensions to improve created SDKs.
Automating this process as part of a CI/CD pipeline.

If you want to follow along, you can use the tRPC Speakeasy Bar example repository.

The SDK Creation Pipeline

With Speakeasy, you can create SDKs from an OpenAPI specification.

tRPC does not natively export OpenAPI documents, but the trpc-openapi package adds this functionality. We'll start this tutorial by adding trpc-openapi to a project, and then we'll add a script to generate an OpenAPI schema and save it as a file.

The quality of your OpenAPI specification will ultimately determine the quality of created SDKs and documentation, so we'll dive into ways you can improve the generated specification.

With our new and improved OpenAPI specification in hand, we'll take a look at how to create SDKs using Speakeasy.

Finally, we'll add this process to a CI/CD pipeline so that Speakeasy automatically creates fresh SDKs whenever your tRPC API changes in the future.

Requirements

To follow along with this tutorial, you will need:

An existing tRPC app, or you can clone our example application.
Some familiarity with tRPC.
Node.js installed (we used Node v20.5.1).
The Speakeasy CLI installed. You'll use the CLI to create the SDK once you have generated your OpenAPI spec.

Supported OpenAPI Versions

Speakeasy supports OpenAPI v3 and v3.1. As of October 2023, trpc-openapi can generate schemas that adhere to the OpenAPI v3.0.3 specification.

This OpenAPI version is not a limitation, but it is important to keep the versions used in mind when debugging code generation. Refer to the OpenAPI Initiative for an overview of the differences between OpenAPI 3.0 and 3.1.0.

Why Speakeasy and tRPC?

tRPC's focus on type safety and developer experience sets it apart from other TypeScript API frameworks. By using TypeScript's type system along with a schema library like Zod, tRPC allows your server and client code to share types.

One of the tRPC's stated goals is to cut down on the need for codegen, but we believe there is still a place for code generation in the tRPC ecosystem. While tRPC's default client is useful for writing internal clients in a monorepo where a client can import the server's AppRouter, it does not make it easy to publish production-ready SDKs for use by internal and external developers. Nor does tRPC's type-safety extend to SDKs in languages other than TypeScript.

Speakeasy can help you create type-safe, production-ready SDKs for your tRPC API in various languages, so that you can focus on building your API, confident that your users will have a great developer experience.

How To Generate an OpenAPI Spec With tRPC

We'll use trpc-openapi to create REST endpoints for our tRPC procedures and then create the OpenAPI spec that describes these endpoints.

To generate an OpenAPI spec for tRPC, we'll use trpc-openapi to create REST endpoints for our tRPC procedures, then create an OpenAPI document that describes these endpoints.

Add trpc-openapi to a Project

Install trpc-openapi:

npm install trpc-openapi

Use initTRPC.meta<OpenApiMeta>() to create a new tRPC instance with OpenAPI support:

import { initTRPC } from "@trpc/server";
import { OpenApiMeta } from "trpc-openapi";

const t = initTRPC.meta<OpenApiMeta>().create();

Add OpenAPI meta to a procedure by passing an openapi object to the meta function. This object contains the HTTP method and path for the generated REST endpoint.

import { initTRPC } from "@trpc/server";
import { OpenApiMeta } from "trpc-openapi";
import { z } from "zod";

const t = initTRPC.meta<OpenApiMeta>().create();

export const appRouter = t.router({
  findByProductCode: t.procedure
    .meta({ openapi: { method: "GET", path: "/find" } })
    .input(z.object({ code: z.string() }))
    .output(z.object({ drink: z.object({ name: z.string() }) }))
    .query(async ({ input }) => {
      const drink = {
        name: "Old Fashioned",
      }
      return { drink: drink };
    }),
});

Add a new script to generate an OpenAPI document based on the tRPC router:

import { generateOpenApiDocument } from "trpc-openapi";

import { appRouter } from "./router";

export const openApiDocument = generateOpenApiDocument(appRouter, {
  title: 'tRPC OpenAPI',
  version: '1.0.0',
  baseUrl: 'http://localhost:3000',
});

Add a script to save the generated OpenAPI document to a file:

import { openApiDocument } from "./openapi";

console.log(JSON.stringify(openApiDocument, null, 2));

Run the script to generate an OpenAPI document:

ts-node generateOpenApi.ts > openapi-spec.json

Add this document to the package.json file as a script:

{
  "scripts": {
    "generate-openapi": "ts-node generateOpenApi.ts > openapi-spec.json"
  }
}

From now on, we can generate an OpenAPI document by running npm run generate-openapi.

When we inspect the generated OpenAPI document, we can see that it contains a single endpoint for the findByProductCode procedure, but it's missing a lot of information.

Let's see how we can improve this document.

How To Improve the OpenAPI Info Section

The OpenAPI info section contains information about the API, such as the title, description, and version. Speakeasy uses this information to create documentation and SDKs.

The GenerateOpenApiDocumentOptions type from trpc-openapi allows us to add this information to our OpenAPI document:

export type GenerateOpenApiDocumentOptions = {
    title: string;
    description?: string;
    version: string;
    baseUrl: string;
    docsUrl?: string;
    tags?: string[];
    securitySchemes?: OpenAPIV3.ComponentsObject['securitySchemes'];
};

We can add this information to our generateOpenApiDocument call:

import { generateOpenApiDocument } from "trpc-openapi";

import { appRouter } from "./router";

export const openApiDocument = generateOpenApiDocument(appRouter, {
  title: "Speakeasy Bar API",
  description: "An API to order drinks from the Speakeasy Bar",
  version: "1.0.0",
  baseUrl: "http://localhost:3000",
  docsUrl: "http://example.com/docs",
  tags: ["drinks"],
});

Run npm run generate-openapi and see how this information is added to the OpenAPI document:

{
  "openapi": "3.0.3",
  "info": {
    "title": "Speakeasy Bar API",
    "description": "An API to order drinks from the Speakeasy Bar",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:3000"
    }
  ],
  "tags": [
    {
      "name": "drinks"
    }
  ],
  "externalDocs": {
    "url": "http://example.com/docs"
  },
  // ...
}

Improving the OpenAPI Paths

We can improve our OpenAPI document by adding fields to the procedure's input and output schemas, and by adding examples, documentation, and metadata.

Expanding the Procedure’s Input and Output Schemas

Let's create a Drink model and add a few field types to see how these are represented in the OpenAPI document.

Create a new file called models.ts and specify a Drink model using Zod:

import { z } from "zod";

const DrinkType = z.enum([
    "NON_ALCOHOLIC",
    "BEER",
    "WINE",
    "SPIRIT",
    "OTHER",
]).describe('The type of drink');
type DrinkType = z.infer<typeof DrinkType>;

export const ProductCode = z.string().describe('The product code of the drink');
export type ProductCode = z.infer<typeof ProductCode>;

export const DrinkSchema = z.object({
    name: z.string().describe('The name of the drink'),
    type: DrinkType,
    price: z.number().describe('The price of the drink'),
    stock: z.number().describe('The number of drinks in stock'),
    productCode: ProductCode,
    description: z.string().nullable().describe('A description of the drink'),
});

export type Drink = z.infer<typeof DrinkSchema>;

Back in the router.ts file, import these models and update the procedure's input and output schemas. In the example app, we also added a mock database.

import { initTRPC } from "@trpc/server";
import { OpenApiMeta } from "trpc-openapi";
import { z } from "zod";

import { ProductCode, DrinkSchema } from "./models";
import { db } from "./db";  // Mock database

const t = initTRPC.meta<OpenApiMeta>().create();

export const appRouter = t.router({
  findByProductCode: t.procedure
    .meta({ openapi: { method: "GET", path: "/find" } })
    .input(z.object({ code: ProductCode }))
    .output(z.object({ drink: DrinkSchema.optional() }))
    .query(async ({ input }) => {
      const drink = await db.drink.findByProductCode(input.code);
      return { drink: drink };
    }),
});

If we regenerate the OpenAPI document, we can see that the Drink model is now included in the document with all of its fields:

{
   "paths": {
    "/find": {
      "get": {
        "operationId": "findByProductCode",
        "summary": "Find a drink by product code",
        "description": "Pass the product code of the drink to search for",
        "tags": [
          "drinks"
        ],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The product code of the drink",
            "example": "1234"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "drink": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "The name of the drink"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "NON_ALCOHOLIC",
                            "BEER",
                            "WINE",
                            "SPIRIT",
                            "OTHER"
                          ],
                          "description": "The type of drink"
                        },
                        "price": {
                          "type": "number",
                          "description": "The price of the drink"
                        },
                        "stock": {
                          "type": "number",
                          "description": "The number of drinks in stock"
                        },
                        "productCode": {
                          "type": "string",
                          "description": "The product code of the drink"
                        },
                        "description": {
                          "type": "string",
                          "nullable": true,
                          "description": "A description of the drink"
                        }
                      },
                      "required": [
                        "name",
                        "type",
                        "price",
                        "stock",
                        "productCode",
                        "description"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                },
                "example": {
                  "drink": {
                    "name": "Beer",
                    "type": "BEER",
                    "price": 5,
                    "stock": 10,
                    "productCode": "1234",
                    "description": "A nice cold beer"
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/error"
          }
        }
      }
    }
  },
  // ...
}

Speakeasy will use the descriptions in these fields to create documentation for the SDK.

OpenAPI Model Schemas in tRPC

At Speakeasy, we recommend using OpenAPI model schemas so that schemas are reusable across multiple procedures. This simplifies SDK code creation, makes it easier to maintain your OpenAPI document, and provides a better developer experience for your users.

At the time of writing, there is an open issue on the tRPC repository to add support for OpenAPI model schemas. Until this is implemented, we'll need to be content with the duplication of schemas across procedures.

Under the hood, trpc-openapi uses the Zod to Json Schema package, which supports custom strategies for generating references to schemas, but this functionality is not yet exposed in trpc-openapi.

Adding a Summary, Description, Examples, and Tags to a Procedure

We can enrich our OpenAPI document by adding a summary, description, examples, and tags to our procedure's metaobject.

The trpc-openapi package uses these fields to generate the summary, description, example, and tags fields in the OpenAPI document.

The example field is also used to add examples to the input schema.

import { initTRPC } from "@trpc/server";
import { OpenApiMeta } from "trpc-openapi";
import { z } from "zod";

import { ProductCode, DrinkSchema } from "./models";
import { db } from "./db";

const t = initTRPC.meta<OpenApiMeta>().create();

export const appRouter = t.router({
  findByProductCode: t.procedure
    .meta({
      openapi: {
        method: "GET",
        path: "/find",
        summary: "Find a drink by product code",
        description: "Pass the product code of the drink to search for",
        tags: ["drinks"],
        example: {
          request: {
            code: "1234",
          },
          response: {
            drink: {
              name: "Beer",
              type: "BEER",
              price: 5.0,
              stock: 10,
              productCode: "1234",
              description: "A nice cold beer",
            },
          },
        },
      },
    })
    .input(z.object({ code: ProductCode }))
    .output(z.object({ drink: DrinkSchema.optional() }))
    .query(async ({ input }) => {
      const drink = await db.drink.findByProductCode(input.code);
      return { drink: drink };
    }),
});

If we regenerate the OpenAPI document now, we can see that the summary, description, and example fields have been added to it.

Add Metadata to Tags

The trpc-openapi package defines tags as a list of strings, but OpenAPI allows you to add metadata to tags. For example, you can add a description or a link to documentation to a tag.

Since trpc-openapi uses the openapi-types package OpenAPIV3.Document type, which allows tags defined as a list of strings or a list of objects, we can extend our document to include tag objects with metadata even though trpc-openapi uses a list of strings.

Let's add a description to the drinks tag:

import { generateOpenApiDocument } from "trpc-openapi";

import { appRouter } from "./router";

const openApiDocument = generateOpenApiDocument(appRouter, {
  title: "Speakeasy Bar API",
  description: "An API to order drinks from the Speakeasy Bar",
  version: "1.0.0",
  baseUrl: "http://localhost:3000",
  docsUrl: "http://example.com/docs",
  tags: ["drinks"],
});

// add metadata to tags
openApiDocument.tags = [
  {
    name: "drinks",
    description: "Operations related to drinks",
  },
];

export { openApiDocument };

Now we can see that the description field has been added to the drinks tag in the generated OpenAPI document:

{
  "tags": [
    {
      "name": "drinks",
      "description": "Operations related to drinks"
    }
  ],
}

Add Speakeasy Extensions to Methods

The OpenAPI vocabulary can sometimes be insufficient for your code creation needs. For these situations, Speakeasy provides a set of OpenAPI extensions. For example, you may want to give an SDK method a different name from the OperationId. You can use the Speakeasy x-speakeasy-name-override extension to do so.

This time, unfortunately, the openapi-types package OperationObject type does not allow for custom extensions, so we need to add the extension to the generated OpenAPI document manually.

Ideally, we would create a new type that extends OpenAPIV3.Document and adds the x-speakeasy-name-override extension to the OperationObject type, but for this tutorial, we'll keep it simple and add the extension by casting the path item to any.

Let's add an x-speakeasy-name-override extension to the findByProductCode procedure.

First, we extend the OpenAPIV3.OperationObject and OpenAPIV3.Document types to add the x-speakeasy-name-override and other extensions:

import { OpenAPIV3 } from 'openapi-types';

export type IExtensionName = `x-${string}`;
export type IExtensionType = any;
export type ISpecificationExtension = {
    [extensionName: IExtensionName]: IExtensionType;
};

export type ExtendedDocument = OpenAPIV3.Document & ISpecificationExtension;
export type ExtendedOperationObject = OpenAPIV3.OperationObject<ISpecificationExtension>;

Then we import our extended operation type and add the x-speakeasy-name-override extension to the findByProductCode procedure:

import { generateOpenApiDocument } from "trpc-openapi";

import { ExtendedOperationObject } from "./extended-types";
import { appRouter } from "./router";

const openApiDocument = generateOpenApiDocument(appRouter, {
  title: "Speakeasy Bar API",
  description: "An API to order drinks from the Speakeasy Bar",
  version: "1.0.0",
  baseUrl: "http://localhost:3000",
  docsUrl: "http://example.com/docs",
  tags: ["drinks"],
});

// add metadata to tags
openApiDocument.tags = [
  {
    name: "drinks",
    description: "Operations related to drinks",
  },
];

if (
  openApiDocument.paths &&
  openApiDocument.paths["/find"] &&
  openApiDocument.paths["/find"].get
) {
  (openApiDocument.paths["/find"].get as ExtendedOperationObject)[
    "x-speakeasy-name-override"
  ] = "searchDrink";
}

export { openApiDocument };

Add Retries to an SDK With `x-speakeasy-retries`

Speakeasy can create SDKs that follow custom rules for retrying failed requests. For instance, if your server fails to return a response within a specified time, you may want your users to retry their request without clobbering your server.

Add retries to Speakeasy-created SDKs by adding a top-level x-speakeasy-retries schema to your OpenAPI spec. You can also override the retry strategy per operation by adding x-speakeasy-retries.

Adding Global Retries and Retries per Endpoint

Let's add a global retry strategy to our OpenAPI document and override it for our findByProductCode procedure.

import { generateOpenApiDocument } from "trpc-openapi";

import { ExtendedDocument, ExtendedOperationObject } from "./extended-types";
import { appRouter } from "./router";

const openApiDocument = generateOpenApiDocument(appRouter, {
  title: "Speakeasy Bar API",
  description: "An API to order drinks from the Speakeasy Bar",
  version: "1.0.0",
  baseUrl: "http://localhost:3000",
  docsUrl: "http://example.com/docs",
  tags: ["drinks"],
});

// add metadata to tags
openApiDocument.tags = [
  {
    name: "drinks",
    description: "Operations related to drinks",
  },
];

(openApiDocument as ExtendedDocument)["x-speakeasy-retries"] = {
  strategy: "backoff",
  backoff: {
    initialInterval: 500,
    maxInterval: 60000,
    maxElapsedTime: 3600000,
    exponent: 1.5,
  },
  statusCodes: ["5XX"],
  retryConnectionErrors: true,
};

if (
  openApiDocument.paths &&
  openApiDocument.paths["/find"] &&
  openApiDocument.paths["/find"].get
) {
  (openApiDocument.paths["/find"].get as ExtendedOperationObject)[
    "x-speakeasy-name-override"
  ] = "searchDrink";
  (openApiDocument.paths["/find"].get as ExtendedOperationObject)[
    "x-speakeasy-retries"
  ] = {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      maxElapsedTime: 3600000,
      exponent: 1.5,
    },
    statusCodes: ["5XX"],
    retryConnectionErrors: true,
  };
}

export { openApiDocument };

Regenerate the OpenAPI document and you can see that the x-speakeasy-retries field has been added to the document.

{
  "x-speakeasy-retries": {
    "strategy": "backoff",
    "backoff": {
      "initialInterval": 500,
      "maxInterval": 60000,
      "maxElapsedTime": 3600000,
      "exponent": 1.5
    },
    "statusCodes": [
      "5XX"
    ],
    "retryConnectionErrors": true
  },
  // ...
}

How To Create an SDK Based on the OpenAPI Spec

After following the steps above, we have an OpenAPI spec that is ready to use as the basis for a new SDK. Now we'll use Speakeasy to create an SDK.

In the root directory of your project, run the following:

speakeasy generate sdk \
    --schema openapi-spec.json \
    --lang typescript \
    --out ./sdk

This command uses Speakeasy to create a new TypeScript SDK based on the OpenAPI spec we generated and saved as openapi-spec.json. The Speakeasy CLI saves the new SDK in the ./sdk directory.

Add SDK Creation to GitHub Actions

The Speakeasy sdk-generation-action repository provides workflows to integrate the Speakeasy CLI in your CI/CD pipeline so that your client SDKs are recreated when your OpenAPI spec changes.

You can set up Speakeasy to automatically push a new branch to your SDK repositories so that your engineers can review and merge the SDK changes.

For an overview of how to set up automation for your SDKs, see the Speakeasy SDK Generation Action and Workflows documentation.

Create Production-Ready SDKs with Goa

Tatiana Caciur — Wed, 22 Nov 2023 15:40:23 +0000

Generate SDKs with Goa

This tutorial explains how to define an application programming interface (API) service written in Go with Goa, convert it to an OpenAPI schema with Goa, and convert that to software development kits (SDKs) in multiple languages with Speakeasy. (OpenAPI used to be known as Swagger, which is now a set of tools that can be used with OpenAPI schemas.)

Below is a graphical summary of the creation process.

    flowchart LR
    design.go --> Goa
    Goa --> api[OpenAPI schema]
    Goa --> cli[Client API CLI]
    Goa --> client[Client Go code]
    Goa --> server[Server Go code]
    api --> Speakeasy
    Speakeasy --> ts[TypeScript SDK]
    Speakeasy --> c[C# SDK]
    Speakeasy --> p[Go SDK]
    Speakeasy --> etc[Other SDKs...]

We will talk you through creating a complete code example. By the end of the tutorial, you will have a working API service running in Go that you call through TypeScript code in an SDK.

Is This Tutorial Right for You?

If you're new to OpenAPI, Go, Goa, or Speakeasy, this is the perfect tutorial to see if they are the appropriate technologies for your service. If you're familiar with Goa, but not with Speakeasy, this is also the right place to start.

But if you definitely want to use your OpenAPI schema as a starting point, and not Go code that is transpiled into a schema, Goa is not the right choice for you. Rather, choose one of the other Go frameworks below.

You also might want to design your schema without choosing any programming language. In this case, you could start with the Swagger schema editor. However, using the elegant Goa design language is a lot simpler than trying to design your schema manually. It also creates all the HTTP and gRPC transport code for you.

Prerequisites

For this tutorial, you only need Docker version 20 or newer. You can complete this tutorial on Linux, macOS, or Windows since Docker commands are not dependent on your operating system or any installed frameworks.

If you are running on Windows, please replace backslashes with forward slashes in the few places where you specify a folder path on your host machine.

Introduction to Goa

The OpenAPI specification is a standard that explains how to create a human and machine-readable schema (.json or .yaml document) for any API service. (This tutorial refers to the standard as "the OpenAPI specification", and the definition you create for your service as "your OpenAPI schema", or just "your schema".)

Goa is a package written in the Go language that allows you to define an API in Go syntax using functions from the Goa design language. Goa uses your definition in its design.go file to create:

An OpenAPI schema that can be used by programmers or tools like Speakeasy to understand your API.
Go code for a client application to call your API.
A command line interface (CLI) to call your API.
The transport-agnostic code to provide the API on a server over protocols like HTTP and gRPC.
Go code stubs for the service itself, which you can complete with business logic.

Other Go OpenAPI Frameworks

Most other Go frameworks generate code from an existing OpenAPI schema and don't allow you to write Go as a starting point. These include:

Swaggest Rest can generate OpenAPI definitions from Go code, but it's not as comprehensive as Goa and does not support gRPC.

Is this related to tsoa?

Tsoa is a popular TypeScript framework similar to Goa that you may encounter in the OpenAPI ecosystem. Speakeasy has a tutorial for it, too.

Goa was created in 2015 and Tsoa in 2016. While Tsoa uses decorators and can work with normal Express.js code, Goa starts with an abstract design document in its domain-specific language (DSL) and uses that to generate code and schemas.

Create the API Specification in Goa

Now that you understand how Goa and Speakeasy are used, let's write some code.

Download the Example Repository

First clone the example repository using the code below. If you don't have Git, you can download the code and unzip it.

git clone https://github.com/ritza-co/speakeasy-goa-example.git;
cd speakeasy-goa-example;

While you will create a demonstration application in the app folder in this tutorial, there is a folder called completed_app in the example repository that has all the final generated code and executable files.

Google Protocol Buffers

Goa generates gRPC code for you. gRPC is an efficient alternative to plain HTTP, over which you can provide your API. It requires the use of protocol buffers, made by Google. Our repository already provides the protoc app for you, in completed_app/lib.

To use more recent versions of protoc in future applications, you can download them from the Protobuf repository.

Set Up Go

First, set up your environment. You'll run a Go Docker container and later you'll install Node.js in it. In a terminal in the speakeasy-goa-example folder, run the commands below. Comments in the commands explain what they do.

mkdir app;
cd app;
cp -r ../completed_app/lib .; # copy protoc into your new app
cp -r ../completed_app/design .; # copy in a simple Goa design file

docker run --name gobox --volume .:/go/src/app -it golang:1.21.2 bash; # start Go in a container and share your app folder with it

You now have an app folder ready to code in, and you're in a terminal in a Go container called gobox in Docker.

If you leave this tutorial and return later, you can start the container and attach to the terminal instead of rebuilding everything:

docker start gobox;
docker exec -it gobox bash;
export PATH=$PATH:/go/src/app/lib;
cd /go/src/app;

If you need to delete the container and start over, run:

docker stop gobox;
docker rm gobox;

Run the following commands in the gobox terminal.

cd /go/src/app;
go mod init app; # create a new Go package in this folder called app
go install goa.design/goa/v3/cmd/goa@v3; # install Goa
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest; # install gRPC
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest;
export PATH=$PATH:/go/src/app/lib; # add protoc to your path

Review the Goa Design File

You now have Goa installed and ready to run against a Goa design file. Let's pause to review the API specification in app/design/design.go. Open the file now.

After importing Goa, the design starts by defining the top-level API:

    var _ = API("club", func() {
        Title("The Speakeasy Club")
        Version("1.0.0")
        Description("A club that serves drinks and plays jazz. A Goa and Speakeasy example.")
        Contact(func() {
            Name("Speakeasy Support")
            URL("https://speakeasy-dev.slack.com/join/shared_invite/zt-1cwb3flxz-lS5SyZxAsF_3NOq5xc8Cjw")
        })
        Docs(func() {
            Description("The Speakeasy Club documentation")
            URL("https://www.speakeasyapi.dev/docs")
        })
        License(func() {
            Name("Apache 2.0")
            URL("https://www.apache.org/licenses/LICENSE-2.0.html")
        })
        TermsOfService("https://www.speakeasyapi.dev/docs/terms-of-service")
        Server("club", func() {
            Description("club server hosts the band and order services.")
            Services("band", "order")
            Host("dev", func() {
                Description("The development host. Safe to use for testing.")
                URI("http://{machine}:51000") // use the machine variable below
                URI("grpc://{machine}:52000")
                Variable("machine", String, "Machine IP Address", func() {
                    Default("localhost")
                })
            })
        })
        Meta("openapi:extension:x-speakeasy-retries", `{
            "strategy":"backoff",
            "statusCodes": "408,504"
        }`)
    })

Note that everything in the Goa DSL is a function. The API function takes a function that runs other functions to specify parts of the overall definition of the API, such as Description, Version, and server endpoints (URLs). To learn all the possible functions Goa provides, read the DSL documentation. To create a simpler, minimal definition, use the Goa getting started guide.

The example you create here provides a virtual jazz club, allowing you to order a digital drink and change the genre of music played. These features are defined in two separate services, order and band. While the club API title corresponds to the server URL and is not visible, the service names are visible in the URLs http://localhost:51000/order and http://localhost:51000/band.

The definitions of the two services are below the API. Let's look at the drinks service.

var _ = Service("order", func() {
    Description("A waiter that brings drinks.")
    Method("tea", func() {
        Description("Order a cup of tea.")
        Payload(func() {
            Field(1, "isGreen", Boolean, "Whether to have green tea instead of normal.")
            Field(2, "numberSugars", Int, "Number of spoons of sugar.")
            Field(3, "includeMilk", Boolean, "Whether to have milk.")
        })
        Result(String)
        HTTP(func() {
            Meta("openapi:tag:Drink operations")
            POST("/tea")
        })
        GRPC(func() {
        })
    })
    Files("/openapi.json", "./gen/http/openapi.json")
})

Here you can see we've defined a single POST method called tea in the order service. The tea method takes a few parameters about how you like your milk and sugar, and returns a string representing a cup of tea.

Note that an HTTP GET method won't accept a complex method body, so you have to use POST for any calls other than simple URL IDs.

Encapsulate With References

Goa automatically moves complex types out of the service definition section and into their own section in the schema. For example, in the generated OpenAPI specification file, the line $ref: '#/components/schemas/TeaRequestBody' refers the order specification for tea to the components section later in the document using the JSON references feature.

Rename With Custom operationIds

If you can't find a function in the Goa documentation that corresponds to an OpenAPI field you are expecting, you can probably add it with the Meta function. Meta will add a field and value to any object.

For example, here's how you can change the default operationId value for a method, which is normally serviceName#methodPath:

Method("play", func() {
  Meta("openapi:operationId", "band#play2")

An operationId is a unique name to clearly identify an operation (method). They are useful to name and discuss operations in documentation and SDKs.

Group Operations With Tags

Speakeasy recommends adding tags to all operations so that you can group operations by tag in generated SDK code and documentation. A tag is just a label, like a comment, that you can add to a method.

The Tag function in Goa has a different meaning than it does in OpenAPI, so you need to use the Meta function again in the HTTP section of a method.

var _ = Service("band", func() {
    Method("play", func() {
        HTTP(func() {
            Meta("openapi:tag:Music operations")

Customize With Extensions

OpenAPI supports fields that are not in the specification. These extensions allow you to add custom data to your schema that might have special meaning to applications like Speakeasy. They start with x-.

Speakeasy provides a set of OpenAPI extensions. For example, you may want to give an SDK method a name different to the operationId:

Method("tea", func() {
  Meta("openapi:extension:x-speakeasy-name-override", "chai")

Retry Calling the Server

Speakeasy provides a schema extension called retries that will create an SDK that automatically retries calling the server if a call fails.

In design.go, retries for timeout errors are enabled for the entire API rather than for an individual service or method. For example, this code:

Meta("openapi:extension:x-speakeasy-retries", `{
    "strategy":"backoff",
    "statusCodes": "504,408"
}`)

Will produce this OpenAPI YAML:

x-speakeasy-retries:
    statusCodes: 408,504
    strategy: backoff

Note that the Meta function had to use JSON syntax in the value to output an extension object with sub-properties.

Generate the API Code With Goa

Generate the client and server code and your OpenAPI schema from your design file by running the commands below in the gobox container.

goa gen app/design;
goa example app/design;

The files created in the container will belong to the root user, and you will not be able to edit them on your host. In a terminal on your host machine, go to the app folder and give yourself permissions to edit the created files:

sudo chown -R $(id -u):$(id -g) .

Rerun this whenever you create a file in the container.

Explore the Generated Files

Goa has written a lot of code for us. Below is everything created under app and what it does. To avoid duplication, there is only an explanation for the band files and not for the order files, because they are services with identical structures.

The following files and folders are created by goa gen, and you may regenerate them when your design.go file changes. You may not edit them manually.

/gen — Contains all definition and communication code for HTTP, gRPC, and schemas. Think of the gen folder as your definitions folder.
/gen/band — Contains transport independent service code.
/gen/band/client.go — Can be imported by client code to make calls to the server.
/gen/band/endpoints.go — Exposes the service code to the transport layers.
/gen/grpc — Contains the server and client code that connects the protoc-generated gRPC server and client code, along with the logic to encode and decode requests and responses.
/gen/grpc/band/pb — Contains the protocol buffer files that describe the band gRPC service.
/gen/grpc/band/pb/goagen_app_band_grpc.pb.go — The output of the protoc tool.
/gen/grpc/cli — Contains the CLI code to build gRPC requests from a terminal.
/gen/http — All HTTP-related transport code, for server and client.
/gen/http/openapi3.yaml — The OpenAPI version 3 schema (next to .json and version 1 schemas)

The following files and folders are created by goa example and you can use them as a starting point to write business logic implementation and tests for your server. You should not regenerate these files when your design.go file changes, rather update them manually. If you haven't started work on your implementation yet and do wish to regenerate the files, delete the existing files first to be certain that Goa recreates them.

/cmd — Contains working placeholder server and CLI code. Think of the cmd folder as your implementation folder.
/cmd/club — A Go package containing your API that you can compile and run to have a working server.
/cmd/club/main.go — The server implementation that you can change to your liking. Add your favorite logger and database manager here.
/cmd/club-cli — A Go package containing a CLI tool that you can compile and call from the terminal to make requests to the server above.
band.go — A placeholder implementation of your service. You can write your business logic here. You might think this file belongs in the /cmd/club folder with the API implementation instead of in the root of the project, but Goa puts the API implementation in the cmd folder and all service implementations in the root.

Take a little time to review /gen/http/openapi3.yaml and see how your design.go functions map to the generated YAML.

Run the Server and CLI

Goa has given us a simple working client and server implementation. Let's compile and test them before starting with Speakeasy.

Run the code below in the container.

go get app/cmd/club; # download dependencies
go build ./cmd/club && go build ./cmd/club-cli; # build the server
./club; # start the server

You now have two executable files called club and club-cli in the app folder. The Club server is running inside Docker. The output should look like this:

[club] 16:20:55 HTTP "Play" mounted on POST /play
[club] 16:20:55 HTTP "./gen/http/openapi.json" mounted on GET /openapi.json
[club] 16:20:55 HTTP "Tea" mounted on POST /tea
[club] 16:20:55 HTTP "./gen/http/openapi.json" mounted on GET /openapi.json
[club] 16:20:55 serving gRPC method band.Band/Play
[club] 16:20:55 serving gRPC method order.Order/Tea
[club] 16:20:55 HTTP server listening on "localhost:51000"
[club] 16:20:55 gRPC server listening on "localhost:52000"

Open another terminal on your host machine and log in to a new Docker terminal:

docker exec -it gobox bash;
cd /go/src/app;
./club-cli --help; # see if you can call the server from a CLI client
./club-cli order tea --body '{"includeMilk": false, "isGreen": false, "numberSugars": 1 }';
./club-cli band play --body '{"style": "Bebop" }';

While the CLI won't receive a response from the server because the implementation is just a placeholder, you can see in the server terminal that it has been successfully called.

Create SDKs With Speakeasy

Before continuing with this tutorial, please register at https://app.speakeasyapi.dev. Once you've registered, create a workspace named club. Browse to API keys. Click "New Api Key". Name it club. Copy and save the key content to use later.

Set Up the Speakeasy CLI

The CLI is the simplest way to use Speakeasy. This tutorial uses Docker, but if you want to install Speakeasy directly on your computer in the future, follow the instructions in the readme.

Run the commands below in the second terminal to gobox that you used to log in to a new Docker terminal. Use the API key you saved earlier in the last line.

apt update;
apt install -y curl unzip sudo nodejs npm; # install dependencies
curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh; # install Speakeasy
export SPEAKEASY_API_KEY=your_api_key_here; # <-- overwrite this with your key

Now Speakeasy is installed in the container. Test it by running:

speakeasy help;

Build an SDK

You now have app/gen/http/openapi3.yaml and Speakeasy, so you can build the SDK. In the container terminal, run:

speakeasy generate sdk --schema /go/src/app/gen/http/openapi3.yaml --lang typescript --out /go/src/app/sdk

The output should be:

Authenticated with workspace successfully - https://app.speakeasyapi.dev/workspaces/
Generating SDK for typescript...
INFO    operation valid {"operation":"band#/openapi.json","type":"paths"}
INFO    operation valid {"operation":"band#play","type":"paths"}
INFO    operation valid {"operation":"order#tea","type":"paths"}
Generating SDK for typescript... done ✓.
For more docs on customizing the SDK check out: https://www.speakeasyapi.dev/docs/customize-sdks

Remember to give yourself permissions to the files on your host machine in another terminal:

sudo chown -R $(id -u):$(id -g) .

While you're using only TypeScript in this tutorial, Speakeasy supports C#, Go, Java, PHP, Python, Ruby, Swift, and TypeScript.

Explore the Generated Files

The root of the Speakeasy-generated sdk folder contains various npm files. Importantly, the package.json file lists the dependencies you need to install before you can run the SDK. The docs folder contains your SDK documentation in Markdown files. The src folder contains the SDK code.

Call Your Service With the SDK

We'll implement the documentation example in sdk/docs/sdks/drinkoperations/README.md.

Make a file called test.js in the app/sdk folder. Insert the code below.

const SDK = require("./dist/index");

(async() => {
  const sdk = new SDK.SDK();

  const res = await sdk.drinkOperations.orderNumberTea({
    includeMilk: true,
    isGreen: false,
    numberSugars: 1584355970564842800,
  });

  if (res.statusCode == 200) {
    console.log('A nice cup of tea');
  }
})();

In the container terminal, install the npm dependencies and run the test file.

cd /go/src/app/sdk;
npm install;
npx tsc --build;
node test.js;

In the first terminal where your club server is still running, you should see that the server has received a request. In the second terminal, you should see it receive A nice cup of tea.

Next Steps

You now know how to make an OpenAPI-compliant web service from a Goa design specification, and how to generate SDKs for it using Speakeasy.

Get Help With Advanced Goa

If you want to build a more complex API and need help understanding Goa, read the full design language specification.

You can also use the Go Slack group to ask for help:

Register for the group at https://invite.slack.golangbridge.org.
Log in at https://gophers.slack.com.
Join the Goa channel to ask questions about the framework.

Perhaps the easiest way to find out how to do something (especially when using Meta) is to search the test cases when you have cloned the source code.

Use Speakeasy Customizations

Review the Speakeasy customizations to see if adding any would make your service more understandable or usable.

How to Create an OpenAPI Spec & SDKs with tsoa

Tatiana Caciur — Thu, 16 Nov 2023 16:07:33 +0000

Integrate tsoa with Speakeasy

In this tutorial, we'll learn how to integrate tsoa (TypeScript OpenAPI) with Speakeasy to generate client SDKs. We'll delve into the Speakeasy SDK generation pipeline and look at how to produce an OpenAPI specification using tsoa to generate an SDK.

If you want to follow along, you can use the tsoa Speakeasy Bar example repository

The SDK Generation Pipeline

You can generate client SDKs using Speakeasy when your API definition in tsoa changes. Many Speakeasy users add SDK generation to their CI workflows to ensure their SDKs are always up-to-date.

To generate an SDK based on your API definition, provide an OpenAPI spec for your API.

How to Generate an OpenAPI Spec with tsoa

To generate an OpenAPI spec using tsoa, we can use the tsoa CLI or call tsoa's generateSpec function. tsoa saves the spec as swagger.json by default, but we can customize the base filename using the configuration option specFileBaseName.

Generating an OpenAPI Spec Using the tsoa CLI

Generate an OpenAPI spec by running the following command in the terminal:

# generate OpenAPI spec
npx tsoa spec

By default, tsoa will use the configuration from the tsoa.json file with your generated routes and metadata to generate an OpenAPI spec.

In our example app, the relevant tsoa.json config is as follows:

{
  "spec": {
    "outputDirectory": "build",
    "specVersion": 3
  }
}

This configures tsoa to output the generated OpenAPI spec in the build directory and to use OpenAPI version 3.

Programmatically Generate an OpenAPI Spec Using tsoa

To generate an OpenAPI spec using the OpenAPI internal generator functions, import generateSpec and call this function by passing a spec config of type ExtendedSpecConfig from tsoa.

The recommended way to generate an OpenAPI Spec is via the CLI as tsoa warns that generateSpec and ExtendedSpecConfig can change in minor or patch releases of tsoa. The example below is illustrative and not included in the example app.

import { generateSpec, ExtendedSpecConfig } from "tsoa";

(async () => {
  const specOptions: ExtendedSpecConfig = {
    basePath: "/api",
    entryFile: "./api/server.ts",
    specVersion: 3,
    outputDirectory: "./build",
    controllerPathGlobs: ["./routeControllers/**/*Controller.ts"],
  };

  await generateSpec(specOptions);
})();

Add the code above to a TypeScript file and run it to generate an OpenAPI spec using the custom configuration defined in specOptions.

Supported OpenAPI Versions

Speakeasy supports OpenAPI version 3 and version 3.1. As of August 2023, tsoa can generate OpenAPI version 2 and version 3 specifications. To use Speakeasy, make sure to configure tsoa to generate OpenAPI v3.

To set the OpenAPI version, add spec.specVersion=3 to your tsoa.json configuration file:

{
  "spec": {
    "specVersion": 3
  }
}

How tsoa Generates OpenAPI `info`

When generating an OpenAPI spec, tsoa tries to guess your API's title, description, and contact details based on values in your project package.json file.

Values in tsoa.json take precedence over those in package.json when configured.

Set OpenAPI `info` in `package.json`

Take this snippet from our example app's package.json file:

{
  "name": "speakeasy-bar-tsoa",
  "version": "1.0.0",
  "description": "Speakeasy Bar API",
  "author": "Speakeasy Support <support@speakeasy.bar> (https://support.speakeasy.bar)",
  "license": "Apache-2.0"
}

By default, tsoa will generate the following spec based on the values above:

info:
  title: speakeasy-bar-tsoa
  version: 1.0.0
  license:
    name: Apache-2.0
  contact:
    name: "Speakeasy Support "
    email: support@speakeasy.bar
    url: "https://support.speakeasy.bar"

tsoa uses the package author as the contact person by default, extracting the author's email address and optional URL from the person format defined by npm.

Set OpenAPI Info Using tsoa Configuration

To manually configure your OpenAPI info section, configure tsoa using the tsoa.json file:

{
  "spec": {
    "name": "Custom API Name",
    "description": "Custom API Description",
    "license": "MIT",
    "version": "1.0.0",
    "contact": {
      "name": "API Contact",
      "email": "help@example.com",
      "url": "http://example.com"
    }
  }
}

After adding this custom configuration, tsoa will use these values instead of those from package.json when generating a spec.

Update tsoa To Generate OpenAPI Component Schemas

Let's see how we can help tsoa generate separate and reusable component schemas for a request body.

Consider the following drink model:

/**
 * The type of drink.
 */
export enum DrinkType {
  COCKTAIL = "cocktail",
  NON_ALCOHOLIC = "non-alcoholic",
  BEER = "beer",
  WINE = "wine",
  SPIRIT = "spirit",
  OTHER = "other",
}

export interface Drink {
  /**
   * The name of the drink.
   * @example "Old Fashioned"
   * @example "Manhattan"
   * @example "Negroni"
   */
  name: string;
  type?: DrinkType;

  /**
   * The price of one unit of the drink in US cents.
   * @isInt
   * @example 1000
   * @example 1200
   * @example 1500
   */
  price: number;

  /**
   * The number of units of the drink in stock, only available when authenticated.
   * @isInt
   * @example 102
   * @example 10
   * @example 0
   */
  stock?: number;

  /**
   * The product code of the drink, only available when authenticated.
   * @example "SP-001"
   * @example "CK-001"
   * @example "CK-002"
   */
  productCode?: string;
}

We'd like to write a controller that updates the name and price fields. The controller should take both fields as body parameters.

We'll start with the example controller below. Note how the body parameters drinkName and price are defined by passing the @BodyProp decorator to the controller function multiple times.

@Route("drink")
export class DrinkController extends Controller {
  @Put("{productCode}")
  public async updateDrink(
    @Path() productCode: string,
    @BodyProp() drinkName?: string,
    @BodyProp() price?: number
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(
      productCode,
      drinkName,
      price
    );

    return drink;
  }
}

This would generate inline parameters without documentation for the UpdateDrink operation in OpenAPI, as shown in the snippet below:

requestBody:
  required: true
  content:
    application/json:
      schema:
        properties:
          drinkName:
            type: string
          price:
            type: integer
        type: object

While perfectly valid, this schema is not reusable and excludes the documentation and examples from our model definition.

We recommend picking fields from the model interface directly and exporting a new interface. We could use the TypeScript utility types Pick and Partial to pick the name and price fields and make both optional:

export interface DrinkUpdateParams
  extends Partial<Pick<Drink, "name" | "price">> {}

In our controller, we can now use DrinkUpdateParams as follows:

@Route("drink")
export class DrinkController extends Controller {
  @Put("{productCode}")
  public async updateDrink(
    @Path() productCode: string,
    @Body() requestBody: DrinkUpdateParams
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(productCode, requestBody);

    return drink;
  }
}

Customizing OpenAPI `operationId` Using tsoa

When generating an OpenAPI spec, tsoa adds an operationId to each operation.

We can customize the operationId in three ways:

Using the @OperationId decorator.
Using the default tsoa operationId generator.
Creating a custom operationId template.

Using the `@OperationId` Decorator

The most straightforward way to customize the operationId is to add the @OperationId decorator to each operation.

In the example below, the custom operationId is updateDrinkNameOrPrice:

@Route("drink")
export class DrinkController extends Controller {
  @OperationId("updateDrinkNameOrPrice")
  @Put("{productCode}")
  public async updateDrink(
    @Path() productCode: string,
    @Body() requestBody: DrinkUpdateParams
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(productCode, requestBody);

    return drink;
  }
}

Using the Default tsoa `operationId` Generator

If a controller method is not decorated with the OperationId decorator, tsoa generates the operationId by converting the method name to title case using the following Handlebars template:

{{titleCase method.name}}

Creating a Custom `operationId` Template

To create a custom operationId for all operations without the @OperationId decorator, tsoa allows us to specify a Handlebars template in tsoa.json. tsoa adds two helpers to Handlebars: replace and titleCase. The method object and controller name get passed to the template as method and controllerName.

The following custom operationId template prepends the controller name and removes underscores from the method name:

{
  "spec": {
    "operationIdTemplate": "{{controllerName}}-{{replace method.name '_' ''}}"
  }
}

Add OpenAPI Tags to tsoa Methods

At Speakeasy, whether you're building a big application or only have a handful of operations, we recommend adding tags to all operations so you can group them by tag in generated SDK code and documentation.

Add Tags to Operations Using Decorators

tsoa provides the @Tags() decorator for controllers and controller methods. The decorator accepts one or more strings as input.

@Route("drink")
@Tags("drinks", "bar")
export class DrinkController extends Controller {
  @OperationId("updateDrinkNameOrPrice")
  @Put("{productCode}")
  @Tags("Drink")
  public async updateDrink(
    @Path() productCode: string,
    @Body() requestBody: DrinkUpdateParams
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(productCode, requestBody);

    return drink;
  }
}

Contrary to the illustrative example above, we recommend adding a single tag per method or controller to ensure that the generated SDK is split into logical units.

Add Metadata to Tags

To add metadata to tags, add a tags object to your tsoa.json:

{
  "spec": {
    "tags": [
      {
        "name": "drinks",
        "description": "Operations related to drinks",
        "externalDocs": {
          "description": "Find out more about drinks",
          "url": "http://example.com"
        }
      },
      {
        "name": "bar",
        "description": "Operations related to the bar"
      },
      {
        "name": "update",
        "description": "Update operations"
      }
    ]
  }
}

Add Speakeasy Extensions to Methods

Sometimes OpenAPI's vocabulary is insufficient for your generation needs. For these situations, Speakeasy provides a set of OpenAPI extensions. For example, you may want to give an SDK method a name different from the OperationId. To cover this use case, we provide an x-speakeasy-name-override extension.

To add these custom extensions to your OpenAPI spec, you can make use of tsoa's @Extension() decorator:

@Route("drink")
@Tags("drinks", "bar")
export class DrinkController extends Controller {
  @OperationId("updateDrinkNameOrPrice")
    @Extension({"x-speakeasy-name-override":"update"})
  @Put("{productCode}")
  @Tags("update")
  public async updateDrink(
    @Path() productCode: string,
    @Body() requestBody: DrinkUpdateParams
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(productCode, requestBody);

    return drink;
  }
}

Add Retries to Your SDK With `x-speakeasy-retries`

Speakeasy can generate SDKs that follow custom rules for retrying failed requests. For instance, if your server fails to return a response within a specified time, you may want your users to retry their request without clobbering your server.

Add retries to SDKs generated by Speakeasy by adding a top-level x-speakeasy-retries schema to your OpenAPI spec. You can also override the retry strategy per operation by adding x-speakeasy-retries.

Adding Global Retries

To add a top-level retries extension to your OpenAPI spec, add a new spec schema to the spec configuration in tsoa.json:

{
  "spec": {
    "spec": {
      "x-speakeasy-retries": {
        "strategy": "backoff",
        "backoff": {
          "initialInterval": 500,
          "maxInterval": 60000,
          "maxElapsedTime": 3600000,
          "exponent": 1.5
        },
        "statusCodes": ["5XX"],
        "retryConnectionErrors": true
      }
    }
  }
}

Adding Retries Per Method

To add retries to individual methods, use the tsoa @Extension decorator.

In the example below, we add x-speakeasy-retries to the updateDrink method:

@Route("drink")
export class DrinkController extends Controller {
  @Put("{productCode}")
  @Extension("x-speakeasy-retries", {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      maxElapsedTime: 3600000,
      exponent: 1.5,
    },
    statusCodes: ["5XX"],
    retryConnectionErrors: true,
  })
  public async updateDrink(
    @Path() productCode: string,
    @Body() requestBody: DrinkUpdateParams,
  ): Promise<Drink> {
    const drink = new DrinksService().updateDrink(productCode, requestBody);

    return drink;
  }
}

How to Generate an SDK based on your OpenAPI Spec

Once you have an OpenAPI spec, use Speakeasy to generate an SDK by calling the following in the terminal:

You can pass in either a YAML or JSON schema in the command below.

speakeasy generate sdk \
    --schema build/swagger.json \
    --lang typescript \
    --out ./sdk

This command uses Speakeasy to generate a new TypeScript SDK based on the OpenAPI spec tsoa generated and saved as build/swagger.json. The Speakeasy CLI saves the new SDK in the ./sdk directory.

Summary

This tutorial explored different configurations and customizations available for the OpenAPI specification generation using tsoa. We've also learned how to assign and customize OpenAPI operationId and OpenAPI tags to our tsoa methods. Finally, we demonstrated how to add retries to your SDKs using x-speakeasy-retries. With this knowledge, you should now be able to leverage tsoa, OpenAPI, and Speakeasy more effectively for your API.

Take a look at our Speakeasy Bar (tsoa) example repository containing all the code from this article.

Craft OpenAPI Specs & Production-Ready SDKs with Fastify

Tatiana Caciur — Thu, 09 Nov 2023 20:45:26 +0000

Generate SDKs with Fastify

In this tutorial, we'll show you how to generate an OpenAPI specification using Fastify so that you can use Speakeasy to generate client SDKs for your API.

Here's what we'll cover:

How to add @fastify/swagger to a Fastify project.
Generate an OpenAPI specification using the Fastify CLI.
Improve the generated OpenAPI specification for better downstream SDK generation.
Using the Speakeasy CLI to generate a client SDK based on our generated OpenAPI specification.
Use the Speakeasy OpenAPI extensions to improve generated SDKs.
How to automate this process as part of a CI/CD pipeline.

Your Fastify project might not be as simple as our example app, but the steps below should translate well to any Fastify project. We'll also look at how to gradually add routes to OpenAPI so that you have the option to ship an SDK that improves API coverage over time.

If you want to follow along, you can use the Fastify Speakeasy Bar example repository.

The SDK Generation Pipeline

With Speakeasy, you can create client SDKs based on an OpenAPI specification. Fastify ships with the @fastify/swagger plugin, which provides convenient shortcuts for generating good OpenAPI specifications. We'll start this tutorial by registering @fastify/swagger in a Fastify project to generate a spec.

The quality of your OpenAPI specification will ultimately determine the quality of generated SDKs and documentation, so we'll dive into ways you can improve the generated specification.

With our new and improved OpenAPI specification in hand, we'll take a look at how to generate client SDKs using Speakeasy.

Finally, we'll add this process to a CI/CD pipeline so that Speakeasy automatically generates fresh SDKs whenever your Fastify API changes in the future.

Requirements

This guide assumes that you have an existing Fastify app, or that you'll clone our example application, and that you have a basic familiarity with Fastify.

You'll need Node.js installed (we used Node v20.5.1), and you'll need to install the Fastify CLI.

Once you have Node.js, you can install the Fastify CLI by running the following in the terminal:

npm install fastify-cli --global

Make sure fastify is in your $PATH:

fastify version

If you can't run fastify using the steps above, you can use npx to run fastify-cli by replacing fastify with fastify-cli in our code samples.

For example:

# fastify version
npx fastify-cli version

Install the Speakeasy CLI to generate the SDK once you have generated your OpenAPI spec.

How To Add "@fastify/swagger" to a Fastify Project

In your Fastify project folder, run the following in the terminal to install @fastify/swagger:

npm install --save @fastify/swagger

To register @fastify/swagger in our Fastify app, we added a new plugin. Here's the simplified plugin we added as plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger);
});

Without any further configuration, you can generate an OpenAPI specification by running the Fastify CLI:

fastify generate-swagger app.js

This should print a basic OpenAPI spec in JSON format.

If you find YAML more readable than JSON, you can add --yaml=true to your fastify commands:

fastify generate-swagger --yaml=true app.js

The option to output YAML is brand new and, while merged, hasn't made it to a release when we wrote this tutorial.

Supported OpenAPI Versions in Fastify and Speakeasy

Fastify can generate OpenAPI specifications in OpenAPI version 2.0 (formerly known as Swagger) or OpenAPI version 3.0.3.

Speakeasy supports OpenAPI 3.x.

We need to configure Fastify to ensure we output an OpenAPI spec that conforms to OpenAPI 3.0.3.

How To Generate a Specification in OpenAPI Version 3.0.3 Using Fastify

In Fastify, the version of the generated OpenAPI specification is determined by the Fastify options object. To use OpenAPI 3.0.3, the options object should contain an object with the key openapi at its root.

Continuing our example above, we'll add an options object when we register @fastify/swagger in plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {},
  });
});

To verify that we now have an OpenAPI 3.0.3 spec, run:

fastify generate-swagger app.js

The output should start with the following JSON:

{
  "openapi": "3.0.3"
  //...
}

How To Add OpenAPI "info" in Fastify

Without customization, @fastify/swagger generates the following info object for our API:

{
  //...
  "info": {
    "version": "8.10.1",
    "title": "@fastify/swagger"
  }
}

We can customize this object by updating our options object in plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      info: {
        title: "Speakeasy Bar API",
        description: "This is a sample API for Speakeasy Bar.",
        termsOfService: "http://example.com/terms/",
        contact: {
          name: "Speakeasy Bar Support",
          url: "http://www.example.com/support",
          email: "support@example.com",
        },
        license: {
          name: "Apache 2.0",
          url: "https://www.apache.org/licenses/LICENSE-2.0.html",
        },
        version: "1.0.1",
      },
    },
  });
});

Fastify copies this info object verbatim, which results in the following info object in our JSON:

{
  "info": {
    "title": "Speakeasy Bar API",
    "description": "This is a sample API for Speakeasy Bar.",
    "termsOfService": "http://example.com/terms/",
    "contact": {
      "name": "Speakeasy Bar Support",
      "url": "http://www.example.com/support",
      "email": "support@example.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.1"
  }
  //...
}

Another common pattern we've seen, included here for completeness, is to reuse information from the project's package.json when generating OpenAPI specs. This pattern takes DRY quite literally, and someone editing the package might not realize the downstream consequences.

To pull information from package.json in plugins/openapi.js:

import packageJson from "../package.json";
import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      info: {
        title: packageJson.name,
        description: packageJson.description,
        version: packageJson.version,
        //...
      },
    },
  });
});

Update Fastify To Generate OpenAPI Component Schemas

Fastify handles validation and serialization for Fastify apps based on schemas defined as JSON Schema but does not enforce separating schemas into reusable components.

Let's start with a hypothetical example in a route definition, routes/drink/index.js:

export default async function (fastify, opts) {
  const schema = {
    params: {
      type: "object",
      properties: {
        drinkId: { type: "string" },
      },
    },
    response: {
      200: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" },
          description: { type: "string" },
        },
      },
    },
  };

  fastify.get("/:drinkId/", { schema }, async function (request, reply) {
    const { drinkId } = request.params;
    return {
      id: drinkId,
      name: "Example Drink Name",
      description: "Example description",
    };
  });
}

The example above would generate the following OpenAPI schema for this route:

{
  "paths": {
    "/drink/{drinkId}/": {
      "get": {
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "drinkId",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Note how the response schema is presented inline. If we defined the schema for another route that returns a drink object similarly, our OpenAPI spec, resulting SDK, and documentation would not present a drink as a reusable component schema.

Fastify provides methods to add and reuse schemas in an application.

As a start, let's separate the response schema and use the Fastify addSchema method:

export default async function (fastify, opts) {
  fastify.addSchema({
    $id: "Drink",
    type: "object",
    properties: {
      name: { type: "string" },
      description: { type: "string" },
    },
  });

  const schema = {
    params: {
      type: "object",
      properties: {
        drinkId: { type: "string" },
      },
    },
    response: {
      200: {
        $ref: "Drink",
      },
    },
  };

  fastify.get("/:drinkId/", { schema }, async function (request, reply) {
    const { drinkId } = request.params;
    return {
      id: drinkId,
      name: "Example Drink Name",
      description: "Example description",
    };
  });
}

We added a field called $id to our drink schema, then called fastify.addSchema() to add this shared schema to the Fastify app. To use this shared schema, we reference it using the JSON Schema $ref keyword, referencing the shared schema $id field.

This generates the following OpenAPI schema:

{
  "components": {
    "schemas": {
      "def-0": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "title": "Drink"
      }
    }
  },
  "paths": {
    "/drink/{drinkId}/": {
      "get": {
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "drinkId",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/def-0"
                }
              }
            }
          }
        }
      }
    }
  }
}

Note how, instead of defining the response schema inline with the path schema, we now have a component schema def-0, which our path's response schema references as #/components/schemas/def-0.

This is already more useful, but if we were to generate an SDK or documentation based on this schema, the autogenerated name def-0 would lead to documentation and methods for a schema component named def-0.

Our next task is to customize this name.

Creating Useful OpenAPI "$ref"s in Fastify

By default, Fastify keeps track of all schemas added with fastify.addSchema() and numbers them. The default internal function that builds these references looks like this:

function buildLocalReference(json, baseUri, fragment, i) {
  if (!json.title && json.$id) {
    json.title = json.$id;
  }
  return `def-${i}`;
}

This function makes it clear where the def-0 reference in our generated OpenAPI specification came from.

Fastify allows us to override the buildLocalReference function as part of our OpenAPI options object in plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      info: {
        title: "Speakeasy Bar API",
        description: "This is a sample API for Speakeasy Bar.",
        version: "1.0.1",
      },
    },
    refResolver: {
      buildLocalReference(json, baseUri, fragment, i) {
        return json.$id || `id-${i}`;
      },
    },
  });
});

By overriding buildLocalReference in the snippet above, we help Fastify to use the $id field as the component schema's reference. If we were to regenerate the OpenAPI spec now, we would see that def-0 is replaced by Drink.

Customizing OpenAPI "operationId" Using Fastify

Speakeasy uses each path's operationId field in the OpenAPI specification to generate method names and documentation in SDKs.

To add operationId to a route, add this field to the route's schema. For example:

fastify.get(
  "/:drinkId/",
  { schema: { operationId: "getDrink" } },
  async function ({ params: { drinkId } }) {
    return {
      id: drinkId,
    };
  }
);

This would generate the following OpenAPI schema:

{
  "/drink/{drinkId}/": {
    "get": {
      "operationId": "getDrink",
      "responses": {
        "200": {
          "description": "Default Response"
        }
      }
    }
  }
}

Add OpenAPI Tags to Fastify Routes

At Speakeasy, whether you're building a big application or only have a handful of operations, we recommend adding tags to all your Fastify routes so you can group them by tag in generated SDK code and documentation.

Add OpenAPI Tags to Routes in Fastify

To add OpenAPI tags to a route in Fastify, add the tags keyword with a list of tags to the route's schema. Here's a simplified example from routes/drink/index.js:

fastify.get(
  "/:drinkId/",
  { schema: { tags: ["drinks"] } },
  async function ({ params: { drinkId } }) {
    return {
      id: drinkId,
    };
  }
);

Add Metadata to Tags

We can add a description and external documentation link to each tag by adding a list of tag objects to the Swagger options object in plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      info: {
        tags: [
          {
            name: "drinks",
            description: "Drink-related endpoints",
            externalDocs: {
              description: "Find out more",
              url: "http://swagger.io",
            },
          },
        ],
      },
    },
  });
});

As with the other keys in the info options, Fastify copies the list of tags to the generated OpenAPI spec verbatim.

Add a List of Servers to the Fastify OpenAPI Spec

When validating an OpenAPI spec, Speakeasy expects a list of servers at the root of the spec. We'll add this to our options object in plugins/openapi.js:

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      servers: [
        {
          url: "http://localhost",
          description: "Development server",
        },
      ],
    },
  });
});

Add Retries to Your SDK With "x-speakeasy-retries"

Adding Global Retries

import fp from "fastify-plugin";
import swagger from "@fastify/swagger";

export default fp(async (fastify) => {
  fastify.register(swagger, {
    openapi: {
      "x-speakeasy-retries": {
        strategy: "backoff",
        backoff: {
          initialInterval: 500,
          maxInterval: 60000,
          maxElapsedTime: 3600000,
          exponent: 1.5,
        },
        statusCodes: ["5XX"],
        retryConnectionErrors: true,
      },
    },
  });
});

Fastify respects OpenAPI extensions that start with x- and copies these to the root of the generated OpenAPI specification.

Adding Retries Per Method

If we want to add a unique retry strategy to a single route, we can add x-speakeasy-retries to the route's schema:

fastify.get(
  "/:drinkId/",
  {
    schema: {
      "x-speakeasy-retries": {
        strategy: "backoff",
        backoff: {
          initialInterval: 500,
          maxInterval: 60000,
          maxElapsedTime: 3600000,
          exponent: 1.5,
        },
        statusCodes: ["5XX"],
        retryConnectionErrors: true,
      },
    },
  },
  async function (request, reply) {
    const { drinkId } = request.params;
    return {
      id: drinkId,
      name: "Example Drink Name",
      description: "Example description",
    };
  }
);

Once again, when generating an OpenAPI spec, Fastify will copy route-specific OpenAPI extensions without any changes.

How To Generate an SDK Based on Your OpenAPI Spec

Before generating an SDK, we need to save the Fastify-generated OpenAPI spec to a file. We'll add the following script to our package.json to generate openapi.json in the root of our project:

{
  "scripts": {
    "openapi": "fastify generate-swagger app.js > openapi.json"
  }
  //...
}

Then we run the following in the terminal:

npm run openapi

After following the steps above, we have an OpenAPI spec that is ready to use as the basis for a new SDK. Now we'll use Speakeasy to generate an SDK.

In the root directory of your project, run the following:

speakeasy generate sdk \
    --schema openapi.json \
    --lang typescript \
    --out ./sdk

This command uses Speakeasy to generate a new TypeScript SDK based on the OpenAPI spec Fastify generated and saved as openapi.json. The Speakeasy CLI saves the new SDK in the ./sdk directory.

Add SDK Generation to Your GitHub Actions

The Speakeasy sdk-generation-action repository provides workflows that can integrate the Speakeasy CLI in your CI/CD pipeline, so your client SDKs are regenerated when your OpenAPI spec changes.

You can set up Speakeasy to automatically push a new branch to your SDK repositories so that your engineers can review and merge the SDK changes.

For an overview of how to set up automation for your SDKs, see the Speakeasy documentation about SDK Generation Action and Workflows.

Summary

In this tutorial, we've learned how to integrate Fastify with Speakeasy to generate client SDKs for your Fastify API. The tutorial guides you through step-by-step instructions on how to do this, from adding @fastify/swagger to a Fastify project and generating an OpenAPI specification, to improving the generated OpenAPI specification for better SDK generation.

It also covers how to use the Speakeasy OpenAPI extensions to improve generated SDKs and how to automate SDK generation as part of a CI/CD pipeline.

Following these steps, you can successfully generate OpenAPI specifications for your Fastify app and improve your API operations.

OneOf, AllOf, AnyOf Oh my! How to define union types in OpenAPI

Tatiana Caciur — Mon, 30 Oct 2023 16:12:14 +0000

The OpenAPI Specification (OAS) is designed to be capable of describing any HTTP API, whether that be REST or something more akin to RPC-based calls. That leads to the OAS having a lot of flexibility baked-in: there are a lot of ways to achieve the exact same result that are equally valid in the eyes of the OAS.

That’s why we’re taking the time to eliminate some of the most common ambiguities that you’ll encounter when you build your OpenAPI documents (OADs). In this case, we’ll be taking a look at how to effectively use anyOf, allOf, and oneOf in your OpenAPI 3.X OADs.

The anyOf, allOf, and oneOf keywords are defined by JSON Schema and used in OpenAPI to define the structure and validation rules for data. They can be used together to define complex and flexible schemas.

oneOf: The value must match exactly one of the subschemas. The oneOf keyword is useful for describing scenarios where a property can be defined with multiple possible data structures, but only one of them is used at a time. For example, if your API accepts a string or an int for a certain field depending on the use case, oneOf would be used. In code generation, it will be generally interpreted as a union type.
allOf: The value must match all of the subschemas. The allOf keyword is useful for describing model composition: the creation of complex schemas via the composition of simpler schemas.
anyOf: The value must match one or more of the subschemas. The anyOf keyword is useful for describing type validation (similar to oneOf), but it can get you into a lot of trouble in code generation. There is no straightforward way for a code generator to interpret what anyOf means, which can lead to undefined or unintended behavior or simply any schema being allowed. We’ll dig into this more later.

Recommended Practices

When you’re writing your OAD, you need to consider your end goals. The distinctions between allOf, oneOf, anyOf are subtle, but the implications on types in a generated SDK can be huge. To avoid downstream problems, we recommend following these rules:

Use oneOf to represent union type object fields.
Use allOf to represent intersection type / composite objects and fields.
Don’t use anyOf unless you absolutely need to.

Below, we will step through each of the different keywords and explain how to use formats, patterns, and additional attributes to give you a spec that is descriptive and explicit.

What is `oneOf`?

The oneOf keyword in JSON Schema and OpenAPI specifies that a value must match exactly one from a given set of schemas.

oneOf is the closest OpenAPI analog to the concept of a union type. A union type is a way to declare a variable or parameter that can hold values of multiple different types. They allow you to make your code more flexible while still providing type safety to users.

Let’s look at an example of how a oneOf is translated into a typescript object:

components:
    schemas:
        Drink:
          type: object
          oneOf:
            - $ref: "#/components/schemas/Cocktail"
            - $ref: "#/components/schemas/Mocktail"

That would produce a type structure like:

type Drink = Cocktail | Mocktail;

What is `allOf`?

The allOf keyword in JSON Schema and OpenAPI combines multiple schemas to create a single object that must be valid against all of the given subschemas.

allOf is the closest OpenAPI analog to an intersection type or a composite data type. You can use allOf to create a new type by combining multiple existing types. The new type has all the features of the existing types.

components:
    schemas:
        MealDeal:
          type: object
          allOf:
            - $ref: "#/components/schemas/Cocktail"
            - $ref: "#/components/schemas/Snack"

That would produce a type structure like:

type MealDeal = Cocktail & Snack;

Pitfall: Construction of Illogical Schemas

allOf has valid use cases, but you can also shoot yourself in the foot fairly easily. The most common problem that occurs when using allOf is the construction of an illogical schema. Consider the following example:

type: object
properties:
  orderId:
    description: ID of the order.
    type: integer
    allOf:
      - $ref: '#/components/schemas/MealDealId'
...
components:
    schemas:
        MealDealId:
            type: string
      description: The id of a meal deal.

The OAS itself doesn’t mandate type validation, so this is technically valid. However, if you try to turn this into functional code, you will quickly realize that you’re trying to make something both an integer and a string at the same time, something that is clearly not possible.

Speakeasy’s implementation of allOf is a work in progress. To avoid the construction of illogical types, we currently construct an object using the superset of fields from the listed schemas. In cases where the base schemas have a collision, we will default to using the object deepest in the list.

What is `anyOf`?

The anyOf keyword in JSON Schema and OpenAPI is the poor misunderstood sibling of oneOf and allOf. There is no established convention about how anyOf should be interpreted, which often leads to some very nasty unintended behavior. The issue arises when anyOf is interpreted to mean that a value must match at least one of the given listed schemas.

There could be a valid use of anyOf to describe an extended match of one element of a list. But that is not currently implemented by any OpenAPI tooling known to us.

Pitfall: Combinatorial Explosion of Type

anyOf leads to a lot of problems in code generation because, taken literally, it describes a combinatorial number of data types. Imagine the following object definition:

components:
    schemas:
        Drink:
          type: object
          anyOf:
            - $ref: "#/components/schemas/Soda"
            - $ref: "#/components/schemas/Water"
                - $ref: "#/components/schemas/Wine"
                - $ref: "#/components/schemas/Spirit"
                - $ref: "#/components/schemas/Beer"

To avoid the explosion of types described below, Speakeasy’s SDK creation interprets anyOf as oneOf.

If you’re doing code generation, you need to explicitly build types to cover all the possible combinations of these 5 liquids (even though most would be disgusting). That would lead you to build over 200 types to cover all the different combinations. That would lead to tremendous bloat in your library. That’s why our recommendation is don’t use anyOf.

Describing Nullable Objects

People sometimes incorrectly use oneOf when they want to indicate that it is possible for an object to be null. It differs based on the the version of OpenAPI you are using, but there are better ways to describe something as nullable.

If you are using OpenAPI 3.0 use the nullable property:

components:
    schemas:
        Drink:
          type: object
            nullable: true

If you are using OpenAPI 3.1, use type: [’object’, ‘null’] to specify that an object is nullable:

components:
    schemas:
        Drink:
            type: [object, 'null']

Conclusion

AnyOf, AllOf, and OneOf are powerful keywords that can be used to define the structure and validation rules for data in OpenAPI.

You’ll notice that this article doesn’t cover the JSON Schema notkeyword. Although this keyword is valid in OAS, its use with code-generation tools leads to immediate problems. How can a code generator generate code for every possible schema except one or a set? This problem has taxed many big-brains, and remains unsolved today.

Here is a link to a blog post that provides more information about defining data types in OpenAPI:

https://speakeasyapi.dev/post/openapi-tips-data-type-formats/

Get Production-Ready Client Libraries from Zod Schemas

Tatiana Caciur — Tue, 24 Oct 2023 14:20:14 +0000

Many Speakeasy users define their TypeScript data parsing schemas using Zod, a powerful and flexible schema validation library for TypeScript.

In this tutorial, we'll take a detailed look at how to set up Zod OpenAPI to generate an OpenAPI schema based on Zod schemas. Then we'll use Speakeasy to read our generated OpenAPI schema and generate a production-ready client SDK.

An Example Schema: Burgers and Orders

We'll start with a tiny example schema describing two main types: Burgers and Orders. A burger is a menu item with an ID, name, and description. An order has an ID, a non-empty list of burger IDs, the time the order was placed, a table number, a status, and an optional note for the kitchen.

Anticipating our CRUD app, we'll also add additional schemas describing fields for creating new objects without IDs or updating existing objects where all fields are optional.

If you would like to follow along, save the following TypeScript code in a new file called index.ts:

import { z } from "zod";

/**
 * The burger schema describes the shape of a burger object as saved in the database.
 */
const burgerSchema = z.object({
  id: z.number().min(1),
  name: z.string().min(1).max(50),
  description: z.string().max(255).optional(),
});

/**
 * The burgerCreateSchema describes the shape of a burger object when creating a new
 * burger.
 */
const burgerCreateSchema = burgerSchema.omit({ id: true });

/**
 * The burgerUpdateSchema describes the shape of a burger object when updating an
 * existing burger.
 */
const burgerUpdateSchema = burgerSchema.partial().omit({ id: true });

/**
 * The orderStatusEnum describes the possible values for the status field of an order.
 */
const orderStatusEnum = z.enum([
  "pending",
  "in_progress",
  "ready",
  "delivered",
]);

/**
 * The orderSchema describes the shape of an order object as saved in the database.
 */
const orderSchema = z.object({
  id: z.number(),
  burger_ids: z.array(z.number().min(1)).nonempty(),
  time: z.string().datetime(),
  table: z.number().min(1),
  status: orderStatusEnum,
  note: z.string().optional(),
});

/**
 * The orderCreateSchema describes the shape of an order object when creating a new
 * order.
 */
const orderCreateSchema = orderSchema.omit({ id: true });

/**
 * The orderUpdateSchema describes the shape of an order object when updating an
 * existing order.
 */
const orderUpdateSchema = orderSchema.partial().omit({ id: true });

An Overview of Zod OpenAPI

Zod OpenAPI is a TypeScript library that helps developers define OpenAPI schemas as Zod schemas. The stated goal of the project is to cut down on code duplication, and it does a wonderful job of this.

Zod schemas map to OpenAPI schemas well, and the changes required to extract OpenAPI documents from a schema defined in Zod are often tiny.

Zod OpenAPI is maintained by one of the contributors to an earlier library called Zod to OpenAPI. If you already use Zod to OpenAPI, the syntax will be familiar and you should be able to use either library. If you'd like to convert your Zod to OpenAPI code to Zod OpenAPI code, the Zod OpenAPI library provides helpful documentation for migrating code.

Install the Zod OpenAPI Library

Use npm to install zod-openapi:

npm install zod-openapi

Extend Zod With OpenAPI

We'll add the openapi method to Zod by calling extendZodWithOpenApi once. Update index.ts to replace the first line with the following:

import { extendZodWithOpenApi } from "zod-openapi";
import { z } from "zod";

extendZodWithOpenApi(z);

Register and Generate a Component Schema

Next, we'll use the new openapi method provided by extendZodWithOpenApi to register an OpenAPI schema for the burgerSchema. Edit index.ts and add .openapi({ref: "Burger"} to the burgerSchema schema object.

We'll also add an OpenAPI generator, OpenApiGeneratorV31, and log the generated component to the console as YAML.

import { extendZodWithOpenApi } from "zod-openapi";
import { z } from "zod";

extendZodWithOpenApi(z);

const burgerSchema = z
  .object({
    id: z.number().min(1),
    name: z.string().min(1).max(50),
    description: z.string().max(255).optional(),
  })
  // Register a Burger schema
  .openapi({
    ref: "Burger",
  });

Add Metadata to Components

To generate an SDK that offers great developer experience, we recommend adding descriptions and examples to all fields in OpenAPI components.

With Zod OpenAPI, we'll call the .openapi method on each field, and add an example and description to each field.

We'll also add a description to the Burger component itself.

Edit index.ts and edit burgerSchema as follows:

const burgerSchema = z
  .object({
    // Add .openapi() call
    id: z.number().min(1).openapi({
      description: "The unique identifier of the burger.",
      example: 1,
    }),
    // Add .openapi() call
    name: z.string().min(1).max(50).openapi({
      description: "The name of the burger.",
      example: "Veggie Burger",
    }),
    // Add .openapi() call
    description: z.string().max(255).optional().openapi({
      description: "The description of the burger.",
      example: "A delicious bean burger with avocado.",
    }),
  })
  // Add an object describing metadata to the Burger component
  .openapi({
    ref: "Burger",
    description: "A burger served at the restaurant.",
  });

Speakeasy will generate documentation and usage examples based on the descriptions and examples we added, but first, we'll need to generate an OpenAPI schema.

Generating an OpenAPI Schema

Now that we know how to register components with metadata for our OpenAPI schema, let's generate a complete schema document.

Use npm to install yaml:

npm install yaml

Update index.ts to call createDocument:

// Add createDocument import
import { extendZodWithOpenApi, createDocument } from "zod-openapi";
// Add yaml import
import * as yaml from "yaml";
import { z } from "zod";

extendZodWithOpenApi(z);

const burgerSchema = z
  .object({
    id: z.number().min(1).openapi({
      description: "The unique identifier of the burger.",
      example: 1,
    }),
    name: z.string().min(1).max(50).openapi({
      description: "The name of the burger.",
      example: "Veggie Burger",
    }),
    description: z.string().max(255).optional().openapi({
      description: "The description of the burger.",
      example: "A delicious bean burger with avocado.",
    }),
  })
  .openapi({
    ref: "Burger",
    description: "A burger served at the restaurant.",
  });

// Call createDocument
const document = createDocument({
  openapi: "3.1.0",
  info: {
    title: "Burger Restaurant API",
    description: "An API for managing burgers at a restaurant.",
    version: "1.0.0",
  },
  servers: [
    {
      url: "https://example.com",
      description: "The production server.",
    },
  ],
  components: {
    schemas: {
      burgerSchema,
    },
  },
});

console.log(yaml.stringify(document));

When we run npx ts-node index.ts, we'll see that the OpenAPI document configuration appears before the components.

openapi: 3.1.0
info:
  title: Burger Restaurant API
  description: An API for managing burgers at a restaurant.
  version: 1.0.0
servers:
  - url: https://example.com
    description: The production server.
components:
  schemas:
    Burger:
      type: object
      properties:
        id:
          type: number
          minimum: 1
          description: The unique identifier of the burger.
          example: 1
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: The name of the burger.
          example: Veggie Burger
        description:
          type: string
          maxLength: 255
          description: The description of the burger.
          example: A delicious bean burger with avocado.
      required:
        - id
        - name
      description: A burger served at the restaurant.

Next, we'll look at how to add paths and webhooks to our OpenAPI schema.

Adding Paths and Webhooks

Paths define the endpoints of your API. For our burger restaurant, we might define endpoints for creating, reading, updating, and deleting burgers and orders.

For this tutorial, we'll register two paths: one to create a burger and another to get a burger by ID.

To register paths and webhooks, we'll define paths as Zod OpenAPI ZodOpenApiOperationObject types, then add our paths and webhooks to the document definition.

import {
  extendZodWithOpenApi,
  // Add ZodOpenApiOperationObject import
  ZodOpenApiOperationObject,
  createDocument,
} from "zod-openapi";
import * as yaml from "yaml";
import { z } from "zod";

extendZodWithOpenApi(z);

// Extract BurgerIdSchema parameter for easier re-use
const BurgerIdSchema = z
  .number()
  .min(1)
  .openapi({
    ref: "BurgerId",
    description: "The unique identifier of the burger.",
    example: 1,
    param: {
      in: "path",
      name: "id",
    },
  });

const burgerSchema = z
  .object({
    id: BurgerIdSchema,
    name: z.string().min(1).max(50).openapi({
      description: "The name of the burger.",
      example: "Veggie Burger",
    }),
    description: z.string().max(255).optional().openapi({
      description: "The description of the burger.",
      example: "A delicious bean burger with avocado.",
    }),
  })
  .openapi({
    ref: "Burger",
    description: "A burger served at the restaurant.",
  });

// Update the burgerCreateSchema definition

const burgerCreateSchema = burgerSchema.omit({ id: true }).openapi({
  ref: "BurgerCreate",
  description: "A burger to create.",
});

const getBurger: ZodOpenApiOperationObject = {
  operationId: "getBurger",
  summary: "Get a burger",
  description: "Gets a burger from the database.",
  requestParams: {
    path: z.object({ id: BurgerIdSchema }),
  },
  responses: {
    "200": {
      description: "The burger was retrieved successfully.",
      content: {
        "application/json": {
          schema: burgerSchema,
        },
      },
    },
  },
};

const createBurger: ZodOpenApiOperationObject = {
  operationId: "createBurger",
  summary: "Create a new burger",
  description: "Creates a new burger in the database.",
  requestBody: {
    description: "The burger to create.",
    content: {
      "application/json": {
        schema: burgerCreateSchema,
      },
    },
  },
  responses: {
    "201": {
      description: "The burger was created successfully.",
      content: {
        "application/json": {
          schema: burgerSchema,
        },
      },
    },
  },
};

const createBurgerWebhook: ZodOpenApiOperationObject = {
  operationId: "createBurgerWebhook",
  summary: "New burger webhook",
  description: "A webhook that is called when a new burger is created.",
  requestBody: {
    description: "The burger that was created.",
    content: {
      "application/json": {
        schema: burgerSchema,
      },
    },
  },
  responses: {
    "200": {
      description: "The webhook was processed successfully.",
    },
  },
};

const document = createDocument({
  openapi: "3.1.0",
  info: {
    title: "Burger Restaurant API",
    description: "An API for managing burgers at a restaurant.",
    version: "1.0.0",
  },
  paths: {
    "/burgers": {
      post: createBurger,
    },
    "/burgers/{id}": {
      get: getBurger,
    },
  },
  webhooks: {
    "/burgers": {
      post: createBurgerWebhook,
    },
  },
  servers: [
    {
      url: "https://example.com",
      description: "The production server.",
    },
  ],
});

console.log(yaml.stringify(document));

When we run npx ts-node index.ts, our script generates the following schema:

openapi: 3.1.0
info:
  title: Burger Restaurant API
  description: An API for managing burgers at a restaurant.
  version: 1.0.0
servers:
  - url: https://example.com
    description: The production server.
paths:
  /burgers:
    post:
      operationId: createBurger
      summary: Create a new burger
      description: Creates a new burger in the database.
      requestBody:
        description: The burger to create.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BurgerCreate"
      responses:
        "201":
          description: The burger was created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Burger"
  "/burgers/{id}":
    get:
      operationId: getBurger
      summary: Get a burger
      description: Gets a burger from the database.
      parameters:
        - in: path
          name: id
          schema:
            $ref: "#/components/schemas/BurgerId"
          required: true
      responses:
        "200":
          description: The burger was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Burger"
webhooks:
  /burgers:
    post:
      operationId: createBurgerWebhook
      summary: New burger webhook
      description: A webhook that is called when a new burger is created.
      requestBody:
        description: The burger that was created.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Burger"
      responses:
        "200":
          description: The webhook was processed successfully.
components:
  schemas:
    BurgerCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: The name of the burger.
          example: Veggie Burger
        description:
          type: string
          maxLength: 255
          description: The description of the burger.
          example: A delicious bean burger with avocado.
      required:
        - name
      description: A burger to create.
    Burger:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/BurgerId"
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: The name of the burger.
          example: Veggie Burger
        description:
          type: string
          maxLength: 255
          description: The description of the burger.
          example: A delicious bean burger with avocado.
      required:
        - id
        - name
      description: A burger served at the restaurant.
    BurgerId:
      type: number
      minimum: 1
      description: The unique identifier of the burger.
      example: 1

Add Tags and Tag Metadata

Tags allow you to organize your operations into groups. This is useful for documentation and SDK generation.

Update index.ts to add tags for the Burger and Order components and paths:

const document = createDocument({
  openapi: "3.1.0",
  info: {
    title: "Burger Restaurant API",
    description: "An API for managing burgers at a restaurant.",
    version: "1.0.0",
  },
  tags: [
    {
      name: "burgers",
      description: "Operations for managing burgers.",
    },
    {
      name: "orders",
      description: "Operations for managing orders.",
    },
  ],
});

Then add the burgers tag to the paths and webhook we created earlier:

const createBurger: ZodOpenApiOperationObject = {
  operationId: "createBurger",
  summary: "Create a new burger",
  description: "Creates a new burger in the database.",
  // Add burgers tag
  tags: ["burgers"],
  requestBody: {
    description: "The burger to create.",
    content: {
      "application/json": {
        schema: burgerCreateSchema,
      },
    },
  },
  responses: {
    "201": {
      description: "The burger was created successfully.",
      content: {
        "application/json": {
          schema: burgerSchema,
        },
      },
    },
  },
};

const getBurger: ZodOpenApiOperationObject = {
  operationId: "getBurger",
  summary: "Get a burger",
  // Add burgers tag
  tags: ["burgers"],
  description: "Gets a burger from the database.",
  requestParams: {
    path: z.object({ id: BurgerIdSchema }),
  },
  responses: {
    "200": {
      description: "The burger was retrieved successfully.",
      content: {
        "application/json": {
          schema: burgerSchema,
        },
      },
    },
  },
};

const createBurgerWebhook: ZodOpenApiOperationObject = {
  operationId: "createBurgerWebhook",
  summary: "New burger webhook",
  // Add burgers tag
  tags: ["burgers"],
  description: "A webhook that is called when a new burger is created.",
  requestBody: {
    description: "The burger that was created.",
    content: {
      "application/json": {
        schema: burgerSchema,
      },
    },
  },
  responses: {
    "200": {
      description: "The webhook was processed successfully.",
    },
  },
};

After adding our tags and generating our schema, we'll see a new top-level tags section in our schema:

tags:
  - name: burgers
    description: Operations for managing burgers.
  - name: orders
    description: Operations for managing orders.

Add Retries to Your SDK With `x-speakeasy-retries`

Speakeasy can generate SDKs that follow custom rules for retrying failed requests. For instance, if your server failed to return a response within a specified time, you may want your users to retry their request without clobbering your server.

To add retries to SDKs generated by Speakeasy, add a top-level x-speakeasy-retries schema to your OpenAPI spec. You can also override the retry strategy per path by adding x-speakeasy-retries to each path.

Adding Global Retries

To add global retries, we'll add a custom key to the document definition:

const document = createDocument({
  openapi: "3.1.0",
  info: {
    title: "Burger Restaurant API",
    description: "An API for managing burgers at a restaurant.",
    version: "1.0.0",
  },
  // Add the x-speakeasy-retries extension to the document
  "x-speakeasy-retries": {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      maxElapsedTime: 3600000,
      exponent: 1.5,
    },
    statusCodes: ["5XX"],
    retryConnectionErrors: true,
  },
});

Adding Retries Per Path

To add x-speakeasy-retries to a single path, update the path and add the x-speakeasy-retries parameter as follows:

const getBurger: ZodOpenApiOperationObject = {
  operationId: "getBurger",
  summary: "Get a burger",
  tags: ["burgers"],
  description: "Gets a burger from the database.",
  requestParams: {
    path: z.object({ id: BurgerIdSchema }),
  },
  responses: {
    "200": {
      description: "The burger was retrieved successfully.",
      content: {
        "application/json": {
          schema: burgerSchema,
        },
      },
    },
  },
  // Add the x-speakeasy-retries extension to the path
  "x-speakeasy-retries": {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      maxElapsedTime: 3600000,
      exponent: 1.5,
    },
    statusCodes: ["5XX"],
    retryConnectionErrors: true,
  },
};

Rerun npx ts-node index.ts to generate a complete schema.

Generate an SDK

With our OpenAPI schema complete, we can now generate an SDK using the Speakeasy SDK generator. We'll follow the instructions in the Speakeasy documentation to generate SDKs for various platforms.

First, write your YAML schema to a new file called openapi.yaml. Run the following in the terminal:

npx ts-node index.ts > openapi.yaml

Then log in to your Speakeasy account or use the Speakeasy CLI to generate a new SDK.

Here's how to use the CLI. In the terminal, run:

speakeasy generate sdk --schema openapi.yaml --lang python --out ./sdk

This generates a new Python SDK in the ./sdk directory.

Example Zod Schema and SDK Generator

The source code for our complete example is available in the zod-burgers repository.

The repository contains a pregenerated Python SDK with instructions on how to generate more SDKs.

You can clone this repository to test how changes to the Zod schema definition results in changes to the generated SDK.

Summary

In this tutorial, we learned how to generate OpenAPI schemas from Zod and create client SDKs with Speakeasy.

By following these steps, you can ensure that your API is well-documented, easy to use, and offers a great developer experience.

How to Wrap Your Terraform Provider for Pulumi

Tatiana Caciur — Fri, 13 Oct 2023 16:10:24 +0000

In this post, we'll show you how to make a Terraform provider available on Pulumi. The article assumes some prior knowledge of Terraform and Pulumi, as well as fluency in Go. If you are new to Terraform providers, please check out our Terraform documentation.

While we provide instructions for building a Pulumi provider here, the resultant provider is not intended for production use. If you want to maintain a Pulumi provider as part of your product offering, we recommend you get in touch with us. Without a partner, providers can become a significant ongoing cost.

Why Users Are Switching From Terraform to Pulumi

Following the recent HashiCorp license change, many users are exploring Pulumi as an alternative to Terraform.

The license change came as a surprise. In response, many companies are considering alternatives to manage their infrastructure-as-code setup. Given the scale of the Terraform ecosystem, it's unlikely that the license change will lead to Terraform disappearing. However, we can expect to see some fragmentation in the market.

If you're used to Terraform, you might notice that Pulumi has fewer providers available. Currently, Pulumi offers 125 providers in their registry, while Terraform boasts an incredible 3,511.

We know the comparison isn't completely fair, though – some users take the "everything-as-code" approach to the extreme, with providers for ordering pizza, building Factorio factories, and placing blocks in Minecraft. But even accounting for hobbyist providers, it's clear that Terraform has significantly more third-party support.

So, let's look at how we can shrink that provider gap...

How Pulumi Differs From Terraform

Pulumi and Terraform are both infrastructure-as-code tools, but they differ in many ways, most importantly in the languages they support.

Terraform programs are defined in the declarative HashiCorp Configuration Language (HCL), while Pulumi allows users to create imperative programs using familiar programming languages like Python, Go, JavaScript, TypeScript, C#, and Java.

This difference has some benefits and drawbacks. With Pulumi's imperative approach, users have more control over how their infrastructure is defined and can write complex logic that isn't easily expressed in Terraform's declarative language. However, this also means that Pulumi code can be less readable than Terraform code.

Bridging Terraform and Pulumi

Pulumi provides two tools to help maintainers build bridge providers. The first is Pulumi Terraform Bridge, which creates Pulumi SDKs based on a Terraform provider schema. The second repository, Terraform Bridge Provider Boilerplate, is a template for building a new Pulumi provider based on a Terraform provider.

While creating a new provider, we'll use the Terraform Bridge Provider Boilerplate, but we'll often call functions from the Pulumi Terraform Bridge.

Pulumi Terraform Bridge is actively maintained, so bear in mind that the requirements and steps below may change with time.

How the Pulumi Terraform Bridge Works

Pulumi Terraform Bridge plays an important role during two distinct phases: design time and runtime.

During design time, Pulumi Terraform Bridge inspects a Terraform provider schema, then generates Pulumi SDKs in multiple languages.

At runtime, the bridge connects Pulumi to the underlying resource via the Terraform provider schema. This way, the Terraform provider schema continues to perform validation and calculates differences between the state in Pulumi and the resource state.

Pulumi Terraform Bridge does not use the Terraform provider binaries. Instead, it creates a Pulumi provider based only on a Terraform provider's Go modules and provider schema.

Step by Step: Creating a Terraform Bridge Provider in Pulumi

The process of creating a Pulumi provider differs slightly depending on how the Terraform provider was created. In the past, most Terraform providers were based on Terraform Plugin SDK. More recent providers are usually based on Terraform Plugin Framework.

The steps you'll follow depend on your Terraform provider. Inspect the go.mod file in your provider to see whether it depends on github.com/hashicorp/terraform-plugin-sdk or github.com/hashicorp/terraform-plugin-framework.

Prerequisites

We manually installed the required tools before noticing that the Terraform Bridge Provider Boilerplate contains a Dockerfile to set up a development image. The manual process wasn't too painful, and either method should work.

The following must be available in your $PATH:

pulumictl
Pulumi
Go 1.17 or 1.latest
NodeJS 14.x – we recommend using nvm to manage Node.js installations
Yarn
TypeScript
Python (called as python3) – for recent versions of macOS, the system-installed version is fine
.NET

Terraform Plugin SDK to Pulumi

As an example of a Terraform provider based on Terraform Plugin SDK, we'll use this Spotify Terraform provider, a small provider for managing Spotify playlists with Terraform.

To create a new Pulumi provider, we'll start with the Terraform Bridge Provider Boilerplate.

Clone the Terraform Bridge Provider Boilerplate

Go to the Terraform Bridge Provider Boilerplate repository in GitHub and click on the green Use this template button. Select Create a new repository from the dropdown.

Select your organization as the owner of the new repository (we'll use speakeasy-api) and create a name for your Pulumi provider. In Pulumi, it is conventional to use pulumi- followed by the resource name in lowercase as the provider name. We'll use pulumi-spotify.

Click Create repository.

Use your Git client of choice to clone your new Pulumi provider repository on your local machine. Our examples below will use the command line on macOS.

In the terminal, replace speakeasy-api with your GitHub organization name in the code below and run it:

git clone git@github.com:speakeasy-api/pulumi-spotify.git
cd pulumi-spotify

Rename Pulumi-Specific Strings in the Boilerplate

The Pulumi Terraform Bridge Provider Boilerplate in its current state is primarily an internal tool used by the Pulumi team to bring Terraform providers into Pulumi. We need to replace a few instances where the boilerplate assumes Pulumi will publish the provider in their GitHub organization.

The Makefile has a prepare command that handles some of the string replacement. In the terminal, replace speakeasy-api with your GitHub organization name in the command below and run it:

make prepare NAME=spotify REPOSITORY=github.com/speakeasy-api/pulumi-spotify

The make command will print the sed commands it ran to replace the boilerplate strings in two files in the repo.

Next, we'll use sed to replace strings in the rest of the repo:

In the terminal, replace speakeasy-api with your GitHub organization name, then run:

find . -not \( -name '.git' -prune \) -not -name 'Makefile' -type f -exec sed -i '' 's|github.com/pulumi/pulumi-spotify|github.com/speakeasy-api/pulumi-spotify|g' {} \;

In the Makefile, replace the ORG variable with the name of your GitHub organization.

Finally, in the provider/resources.go file, manually replace the values in the tfbridge.ProviderInfo struct. Many of these values define names and other fields in the resulting Pulumi SDK packages. Set the GitHubOrg to conradludgate.

Import Your Terraform Provider

Back in the provider/resources.go file, replace the github.com/terraform-providers/terraform-provider-spotify/spotify import with github.com/conradludgate/terraform-provider-spotify/spotify.

In a terminal run the following to change into the provider directory and install requirements.

cd provider
go mod tidy

Fix a Dependency Version

This temporary step is a workaround related to the version of terraform-plugin-sdk imported in the boilerplate.

During our testing, we encountered a bug in terraform-plugin-sdk that was fixed in v2.0.0-20230710100801-03a71d0fca3d.

In provider/go.mod, replace replace github.com/hashicorp/terraform-plugin-sdk/v2 => github.com/pulumi/terraform-plugin-sdk/v2 v2.0.0-20220824175045-450992f2f5b9 with replace github.com/hashicorp/terraform-plugin-sdk/v2 => github.com/pulumi/terraform-plugin-sdk/v2 v2.0.0-20230710100801-03a71d0fca3d. Note the difference in the version strings.

Remove Outdated `make` Step

This temporary step removes a single line from the Makefile that copies a nonexistent scripts directory while building the Node.js SDK. In earlier versions of Pulumi, the Node.js SDK included a scripts folder containing install-pulumi-plugin.js, but Pulumi no longer generates these files.

In the Makefile, remove the cp -R scripts/ bin && \ line from build_nodejs:

makefile
build_nodejs:: VERSION := $(shell pulumictl get version --language javascript)
build_nodejs:: install_plugins tfgen # build the node sdk
    $(WORKING_DIR)/bin/$(TFGEN) nodejs --overlays provider/overlays/nodejs --out sdk/nodejs/
    cd sdk/nodejs/ && \
        yarn install && \
        yarn run tsc && \
        cp -R scripts/ bin && \ # remove this line
        cp ../../README.md ../../LICENSE package.json yarn.lock ./bin/ && \
        sed -i.bak -e "s/\$${VERSION}/$(VERSION)/g" ./bin/package.json

Remove the Nonexistent `prov.MustApplyAutoAliasing()` Function

In provider/resources.go, remove the line prov.MustApplyAutoAliasing() from the Provider() function.

Build the Generator

In the terminal, run:

make tfgen

Go will build the pulumi-tfgen-spotify binary. You can safely ignore any warnings about missing documentation. This can be resolved by mapping documentation from Terraform to Pulumi, but we won't cover that in this guide because the Pulumi boilerplate code does not include this step yet.

Build the Provider

In the terminal, run:

make provider

Go now builds the pulumi-resource-spotify binary and outputs the same warnings as before.

Build the SDKs

In the final step, Pulumi generates SDK packages for .NET, Go, Node.js, and Python.

In the terminal, run:

make build_sdks

You can find the generated SDKs in the new sdk directory in your repository.

Terraform Plugin Framework to Pulumi

As we mentioned earlier, more recent Terraform plugins are based on Terraform Plugin Framework instead of Terraform Plugin SDK. The way Terraform Plugin Framework structures Go code adds a few extra steps when bridging a plugin to Pulumi.

The difference is significant enough that Pulumi Terraform Bridge includes a dedicated tool called Pulumi Bridge for Terraform Plugin Framework in its main repository.

As with providers created using Terraform Plugin SDK, Pulumi Bridge for Terraform Plugin Framework needs to create a new Go binary that calls the Terraform plugin's new provider function. Plugins created with Terraform Plugin Framework define their new provider functions in an internal package, which means we can't import the package directly.

To work around this, we'll create a shim that imports the internal package and exposes a function to our bridge.

But we're getting ahead of ourselves. Let's look at a step-by-step example.

Airbyte Terraform Provider

For this example, we'll bridge the Airbyte Terraform provider to Pulumi. While not the focus of this guide, it is worth mentioning that this provider was entirely generated by Speakeasy.

Clone the Terraform Bridge Provider Boilerplate

Go to the Terraform Bridge Provider Boilerplate repository in GitHub and click on the green Use this template button. Select Create a new repository from the dropdown.

Select your organization as the owner of the new repository (we'll use speakeasy-api again) and create a name for your Pulumi provider. Let's use pulumi-airbyte.

Click Create repository.

Use your Git client of choice to clone your new Pulumi provider repository on your local machine. Our examples below will use the command line on macOS.

In the terminal, replace speakeasy-api with your GitHub organization name in the code below and run it:

git clone git@github.com:speakeasy-api/pulumi-airbyte.git
cd pulumi-airbyte

Rename Pulumi-Specific Strings in the Boilerplate

You'll remember that the Pulumi Terraform Bridge Provider Boilerplate in its current state is primarily an internal tool used by the Pulumi team to bring Terraform providers into Pulumi, so we need to replace a few instances where the boilerplate assumes Pulumi will publish the provider in their GitHub organization.

The Makefile has a prepare command that handles some of the string replacement. In the terminal, replace speakeasy-api with your GitHub organization name in the command below and run it:

make prepare NAME=airbyte REPOSITORY=github.com/speakeasy-api/pulumi-airbyte

The make command will print the sed commands it ran to replace the boilerplate strings in two files in the repo.

Next, we'll use sed to replace strings in the rest of the repo.

In the terminal, replace speakeasy-api with your GitHub organization name, then run:

find . -not \( -name '.git' -prune \) -not -name 'Makefile' -type f -exec sed -i '' 's|github.com/pulumi/pulumi-airbyte|github.com/speakeasy-api/pulumi-airbyte|g' {} \;

In the Makefile, replace the ORG variable with the name of your GitHub organization.

In the provider/resources.go file, manually replace the values in the tfbridge.ProviderInfo struct. Many of these values define names and other fields in the resulting Pulumi SDK packages.

Most importantly, in provider/resources.go, replace fmt.Sprintf("github.com/pulumi/pulumi-%[1]s/sdk/", mainPkg), with fmt.Sprintf("github.com/speakeasy-api/pulumi-%[1]s/sdk/", mainPkg),:

  ImportBasePath: filepath.Join(
-   fmt.Sprintf("github.com/pulumi/pulumi-%[1]s/sdk/", mainPkg),
+   fmt.Sprintf("github.com/speakeasy-api/pulumi-%[1]s/sdk/", mainPkg),
    tfbridge.GetModuleMajorVersion(version.Version),

Remember to replace speakeasy-api with your organization name.

Remove Outdated `make` Step

In the Makefile, remove the cp -R scripts/ bin && \ line from build_nodejs:

build_nodejs:: VERSION := $(shell pulumictl get version --language javascript)
build_nodejs:: install_plugins tfgen # build the node sdk
    $(WORKING_DIR)/bin/$(TFGEN) nodejs --overlays provider/overlays/nodejs --out sdk/nodejs/
    cd sdk/nodejs/ && \
        yarn install && \
        yarn run tsc && \
        cp -R scripts/ bin && \ # remove this line
        cp ../../README.md ../../LICENSE package.json yarn.lock ./bin/ && \
        sed -i.bak -e "s/\$${VERSION}/$(VERSION)/g" ./bin/package.json

Remove the Nonexistent ‘prov.MustApplyAutoAliasing()’ Function

In provider/resources.go, remove the line prov.MustApplyAutoAliasing() from the Provider() function.

Clone the terraform-provider-airbyte repository (replace the destination with your destination):

git clone git@github.com:airbytehq/terraform-provider-airbyte.git /Users/speakeasy/terraform-provider-airbyte
cd /Users/speakeasy/terraform-provider-airbyte

Replace the module name:

sed -i '' '1s|.*|module github.com/airbytehq/terraform-provider-airbyte|' go.mod

Replace the module name in imports:

find . -name '*.go' -print0 | xargs -0 sed -i '' 's|airbyte/internal|github.com/airbytehq/terraform-provider-airbyte/internal|g'

In the steps below, replace /Users/speakeasy/terraform-provider-airbyte with your local terraform-provider-airbyte repository.

Create a Shim To Import the Internal New Provider Function

Start with a new directory called provider/shim in your pulumi-airbyte project:

mkdir provider/shim

Add a go.mod file to this directory with the following contents:

module github.com/airbytehq/terraform-provider-airbyte/shim

go 1.18

// TODO: This replacement is necessary only because airbytehq/terraform-provider-airbyte is not in https://pkg.go.dev/ and the module name is not an FQDN
// So to work around this we clone the terraform-provider-airbyte code and rewrite references to it to the local version.
replace github.com/airbytehq/terraform-provider-airbyte => /Users/speakeasy/terraform-provider-airbyte

require (
  github.com/airbytehq/terraform-provider-airbyte v0.0.0
  github.com/hashicorp/terraform-plugin-framework v1.3.5
)

Now we'll add shim.go to this directory:

package shim

import (
    tfpf "github.com/hashicorp/terraform-plugin-framework/provider"
    "github.com/airbytehq/terraform-provider-airbyte/internal/provider"
)

func NewProvider() tfpf.Provider {
    return provider.New("dev")()
}

Add Shim Requirements

To have Go gather the requirements for our shim module, run the following from the root of the project:

cd provider/shim
go mod tidy
cd ../..

Import the New Shim Provider and the Terraform Package Framework Bridge

In provider/resources.go, edit your imports to look like this (replace speakeasy-api with your organization name):

import (
    "fmt"
    "path/filepath"

    "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge"
    "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge/tokens"
    shim "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim"
    // Import the Pulumi Terraform Framework Bridge:
    pf "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge"
    "github.com/pulumi/pulumi/sdk/v3/go/common/resource"
    "github.com/speakeasy-api/pulumi-airbyte/provider/pkg/version"
    // Import our shim:
    airbyteshim "github.com/airbytehq/terraform-provider-airbyte/shim"
)

Instantiate the Shimmed Provider

In provider/resources.go, replace shimv2.NewProvider(airbyte.Provider()) with pf.ShimProvider(airbyteshim.NewProvider()):

func Provider() tfbridge.ProviderInfo {
    // Instantiate the Terraform provider
-   p := shimv2.NewProvider(airbyte.Provider())
+   p := pf.ShimProvider(airbyteshim.NewProvider())

Add the Shim Module as a Requirement

Edit provider/go.mod, and change the requirements to the following:

require (
    github.com/airbytehq/terraform-provider-airbyte/shim v0.0.0
    github.com/pulumi/pulumi-terraform-bridge/pf v0.17.0
    github.com/pulumi/pulumi-terraform-bridge/v3 v3.61.0
)

Also in provider/go.mod, replace github.com/airbytehq/terraform-provider-airbyte/shim with ./shim as shown below, to let the Go compiler look for the shim in our local repository:

replace (
    github.com/airbytehq/terraform-provider-airbyte/shim => ./shim
  // TODO: The following replacement is only necessary because the terraform-provider-airbyte Go module is not named github.com/airbytehq/terraform-provider-airbyte and it does not appear in the Go package registry
  // This replaces references to github.com/airbytehq/terraform-provider-airbyte with a reference to our local terraform-provider-airbyte repository
  github.com/airbytehq/terraform-provider-airbyte => /Users/speakeasy/terraform-provider-airbyte
)

Install Go Requirements

From the root of the project, run:

cd provider
go mod tidy
cd ..

Build the Generator

In the terminal, run:

make tfgen

Go will build the pulumi-tfgen-airbyte binary. You can safely ignore any warnings about missing documentation. The missing documentation warnings can be resolved by mapping documentation from Terraform to Pulumi, but we won't cover that in this guide as the Pulumi boilerplate code does not include this step yet.

Build the Provider

In the terminal, run:

make provider

Go now builds the pulumi-resource-airbyte binary and outputs the same warnings as before.

Build the SDKs

In the final step, Pulumi generates SDK packages for .NET, Go, Node.js, and Python.

In the terminal, run:

make build_sdks

You can find the generated SDKs in the new sdk directory in your repository.

Summary

We hope this comparison of Terraform and Pulumi and our step-by-step guide to bridging a Terraform provider into Pulumi has been useful to you. You should now be able to create a Pulumi provider based on your Terraform provider.

Speakeasy can help you generate a Terraform provider based on your OpenAPI specifications. Follow our documentation to enter this exciting ecosystem.

Speakeasy also has a Pulumi target in beta. Join our Slack community to discuss our upcoming Pulumi release or for expert advice on Terraform providers.

Introducing Speakeasy Suggest - Automatic OpenAPI Spec Maintenance

Tatiana Caciur — Wed, 04 Oct 2023 19:16:24 +0000

Speakeasy Suggest, our AI-powered tool for automatically improving OpenAPI specs, is available now through the Speakeasy CLI or as a Github workflow. Provide your own OpenAI API key, or simply use ours by default. We’d love to hear your feedback in our Slack community!

Stay tuned for more posts on Suggest output as Github PRs when configuring it as a workflow, interesting results on a variety of specs, and its downstream effects on Speakeasy-generated SDKs!

✨ We plan on open sourcing the core of our LLM-based agent for general-purpose use. Its primary function will be to serve as a JSON document transformer that receives a custom validation function, list of errors, and original document as inputs.

Background

At Speakeasy, we’ve been automating the creation of high-quality developer surfaces for API companies around the world. These include SDKs across multiple languages and even Terraform providers. Today, our generation logic is built on top of OpenAPI, requiring users to supply an OpenAPI schema to effectively use our tooling and generate these surfaces.

Unfortunately, OpenAPI is a complicated specification with lots of potential for misconfiguration and unnecessary repetition. For example, the following schema operations contain duplicate operationIDs (i.e., listDrinks), duplicate inline schema objects, and no examples.

...
/drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security:
        - {}
      tags:
        - drinks
      parameters:
        - name: drinkType
          in: query
          description: The type of drink to filter by. If not provided all drinks will be returned.
          required: false
          schema:
            $ref: "#/components/schemas/DrinkType"
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: The name of the drink.
                      type: string
                    type:
                      $ref: "#/components/schemas/DrinkType"
                    price:
                      description: The price of one unit of the drink in US cents.
                      type: number
                    stock:
                      description: The number of units of the drink in stock, only available when authenticated.
                      type: integer
                      readOnly: true
                    productCode:
                      description: The product code of the drink, only available when authenticated.
                      type: string
                  required:
                    - name
                    - price
...
/drink/{name}:
  get:
    operationId: listDrinks
    summary: Get a drink.
    description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
    tags:
      - drinks
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    responses:
      "200":
        description: A drink.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The name of the drink.
                  type: string
                type:
                  $ref: "#/components/schemas/DrinkType"
                price:
                  description: The price of one unit of the drink in US cents.
                  type: number
                stock:
                  description: The number of units of the drink in stock, only available when authenticated.
                  type: integer
                  readOnly: true
                productCode:
                  description: The product code of the drink, only available when authenticated.
                  type: string
              required:
                - name
                - price
...

As a result of this complexity, many companies create a spec to benefit from the vast ecosystem of OpenAPI tooling (e.g. docs providers), but they don’t have resources or processes in place to maintain it as a first-class resource.

At Speakeasy, we’ve worked with many users’ specs to ensure they are compliant, clean, and accurately depict the state of their API. By leveraging our OpenAPI expertise and custom spec extensions, we’ve been able to create specs that produce idiomatic and human-readable SDKs for dozens of companies. But wouldn’t it be great if we could automate this? Enter Speakeasy Suggest.

Building Speakeasy Suggest

What is it?

Speakeasy Suggest is our LLM-based agent that, given an OpenAPI document, automatically suggests fixes, applies them, and outputs the modified spec. Using AI, we’re able to offload the burden of spec management from API producers. Suggest can be invoked through both the Speakeasy CLI (outputs modified spec to the local filesystem) and our GitHub Action (creates PR) today.

Applying Suggest on the invalid spec above, we produce a valid document with unique operationIDs, re-use of common objects where applicable, and better examples.

components:
  schemas:
    ...
    Drink:
      type: object
      properties:
        name:
          description: The name of the drink.
          type: string
        type:
          $ref: "#/components/schemas/DrinkType"
        price:
          description: The price of one unit of the drink in US cents.
          type: number
        stock:
          description: The number of units of the drink in stock, only available when authenticated.
          type: integer
          readOnly: true
        productCode:
          description: The product code of the drink, only available when authenticated.
          type: string
      required:
        - name
        - price
      example:
        name: Old Fashioned
        type: cocktail
        price: 1000
        stock: 50
        productCode: EX123
...
/drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security:
        - {}
      tags:
        - drinks
      parameters:
        - name: drinkType
          in: query
          description: The type of drink to filter by. If not provided all drinks will be returned.
          required: false
          schema:
            $ref: "#/components/schemas/DrinkType"
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
        ...
/drink/{name}:
  get:
    operationId: getDrink
    summary: Get a drink.
    description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
    tags:
      - drinks
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        example: CocaCola
    responses:
      "200":
        description: A drink.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Drink"
      ...
...

For the remainder of this post, we’d like to delve deeper into the decision-making and engineering challenges behind Speakeasy Suggest. To do that, we’ll start from the beginning.

Good Input = Good Output

Just as a polished OpenAPI spec may be used to generate high-quality SDKs, an LLM requires input with sufficient specificity and detail to produce useful suggestions for a document. It became quickly obvious to us that dumping a spec and naively asking an LLM to “make it better” would not be fruitful.

We found that our in-house validator (i.e. speakeasy validate from our CLI) would be effective at adding a more specific, deterministic context to our LLM prompt. Our validator is built using vacuum, enabling us to specify custom rules. Since these rules are defined by us, they output fixed error messages and line numbers for an array of spec issues. Below is a table highlighting a few of the errors, the suggestions we’d hope to receive from the LLM when including them in the prompt, and explanations of the resulting effects on Speakeasy-generated SDKs when applying those suggestions to the OpenAPI spec.

Validation Error	Suggestion	Explanation
duplicate operationId fields within same tag	Change value of offending operationId's	Compiles without method names conflicting to get a functional SDK
duplicate inline object schemas	Move to shared component	Much shorter and more human-looking class names
missing examples	Add examples for parameter, request bodies, responses, etc.	Generated usage snippets are more human-looking

Each of the validation errors above is present in our invalid spec. So let’s examine the generated Go SDK code before and after running Speakeasy Suggest on the document.

Before

 // ListDrinks - Get a drink.
// Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
func (s *drinks) ListDrinks(ctx context.Context, request operations.ListDrinksRequest) (*operations.ListDrinksResponse, error) {
  ...
  switch {
    case httpRes.StatusCode == 200:
      switch {
      case utils.MatchContentType(contentType, `application/json`):
        var out *operations.ListDrinks200ApplicationJSON
        if err := utils.UnmarshalJsonFromResponseBody(bytes.NewBuffer(rawBody), &out); err != nil {
          return nil, err
        }

        res.ListDrinks200ApplicationJSONObject = out
      ...
      }
    ...
  }
  return res, nil
}

// ListDrinks - Get a list of drinks.
// Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
func (s *drinks) ListDrinks(ctx context.Context, request operations.ListDrinksRequest) (*operations.ListDrinksResponse, error) {
  ...
  switch {
    case httpRes.StatusCode == 200:
      switch {
      case utils.MatchContentType(contentType, `application/json`):
        var out []operations.ListDrinks200ApplicationJSON
        if err := utils.UnmarshalJsonFromResponseBody(bytes.NewBuffer(rawBody), &out); err != nil {
          return nil, err
        }

        res.ListDrinks200ApplicationJSONObjects = out
      ...
      }
    ...
  }
  return res, nil
}

After

// GetDrink - Get a drink.
// Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
func (s *drinks) GetDrink(ctx context.Context, request operations.GetDrinkRequest) (*operations.GetDrinkResponse, error) {
  ...
  switch {
    case httpRes.StatusCode == 200:
      switch {
      case utils.MatchContentType(contentType, `application/json`):
        var out *shared.Drink
        if err := utils.UnmarshalJsonFromResponseBody(bytes.NewBuffer(rawBody), &out); err != nil {
          return nil, err
        }

        res.Drink = out
      ...
      }
    ...
  }
  return res, nil
}

// ListDrinks - Get a list of drinks.
// Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
func (s *drinks) ListDrinks(ctx context.Context, request operations.ListDrinksRequest) (*operations.ListDrinksResponse, error) {
  ...
  switch {
    case httpRes.StatusCode == 200:
      switch {
      case utils.MatchContentType(contentType, `application/json`):
        var out []shared.Drink
        if err := utils.UnmarshalJsonFromResponseBody(bytes.NewBuffer(rawBody), &out); err != nil {
          return nil, err
        }

        res.Drinks = out
      ...
      }
    ...
  }
  return res, nil
}

The code in “Before” would not even compile due to duplicate method names from the conflicting operationIDs. As such, we wouldn’t even generate the SDK without throwing a validation error but have done so here simply to show the differences in output. Also, notice the stark difference in the generated class names the successful responses are being deserialized to (i.e. ListDrinks200ApplicationJSON vs. Drink).

Let’s also examine the differences in the README’s usage snippets your users will reference in their implementation.

Before

...
func main() {
  s := sdk.New(
      sdk.WithSecurity(shared.Security{
          APIKey: "",
      }),
  )

  ctx := context.Background()
  res, err := s.Drinks.ListDrink(ctx, operations.ListDrinkRequest{
      Name: "Willie Gulgowski DVM",
  })
  if err != nil {
      log.Fatal(err)
  }

  if res.ListDrink200ApplicationJSONObject != nil {
      // handle response
  }
}
...

After

...
func main() {
  s := sdk.New(
      sdk.WithSecurity(shared.Security{
          APIKey: "",
      }),
  )

  ctx := context.Background()
  res, err := s.Drinks.GetDrink(ctx, operations.GetDrinkRequest{
      Name: "CocaCola",
  })
  if err != nil {
      log.Fatal(err)
  }

  if res.Drink != nil {
      // handle response
  }
}
...

In addition to better method names and more human-readable classnames, the example value for the drink name parameter is much more relevant. This makes the generated SDK easier for end-users to consume and integrate into their applications.

The validation errors we’ve applied suggestions for are just a small sample of the improvements we can make to an OpenAPI spec. By including them in the prompt, we’ve enabled a feedback loop where even non-critical errors that don’t block SDK generation are encouraged to be added if addressing them improves the quality of the SDK output.

Let’s delve into how we receive these suggestions from the LLM in a format that allows us to apply them to the spec.

Structured Output Parser

In our initial implementation of Suggest, we were only focused on reporting suggestions instead of applying them. Unfortunately, this requires a human in the loop to copy-paste the suggestions themselves. To avoid potential errors and automate the spec management, we needed to be involved in the process of applying the suggestions to our input document as well. This would enable us to revalidate the document upon each applied fix and ensure that overall document correctness was being improved.

Modifying an OpenAPI schema requires us to receive structured output from the LLM that we can apply to the document. We decided to use JSON patch for the format of the suggestion itself. Using langchain-js, this involved defining a custom agent with an output parser specifying the zod schema we pass in to ensure we get LLM output in the right format.

// zod schema
export const SUGGESTION_SCHEMA = z.object({
  suggested_fix: z.string().describe(
    `a simple English description of the suggested JSON patch.
      For example, the JSON patch [{"op": "replace", "path": "/paths/~1pet/post/operationId", "value": "addPet"}] could be described as "Replace the operationId of the POST /pet endpoint with addPet`
  ),
  json_patch: z.string().describe(`suggested fix in the form of a JSON Patch`),
  reasoning: z
    .string()
    .describe(
      "a brief explanation of why you think the suggested fix will resolve the error"
    ),
});

...

// output parser which verifies LLM's final response is formatted according to the zod schema
class JsonOutputParser<T> extends AgentActionOutputParser {
  lc_namespace = ["langchain", "agents", "custom_llm_agent"];
  schema: z.ZodType<T>;

  constructor(schema: z.ZodType<T>) {
    super();

    this.schema = schema;
  }

  async parse(text: string): Promise<AgentAction | AgentFinish> {
    console.log("\n" + text);

    const answerMatch = /```
{% endraw %}
json(.*)
{% raw %}
```/gms.exec(text);
    if (answerMatch) {
      try {
        const json = JSON.parse(answerMatch[1].trim());

        // This will throw an error if the json does not match the schema.
        this.schema.parse(json);

        return {
          log: "Got answer",
          returnValues: json,
        };
      } catch (e) {
        console.log(
          "Answer is invalid JSON or does not match schema. Trying again..."
        );
        return {
          tool: "logger",
          toolInput: `Error: ${e}`,
          log: `Final answer is invalid. It does not conform to the requested output schema. Output schema: ${JSON.stringify(
            zodToJsonSchema(this.schema)
          )}`,
        };
      }
    }
    ...
  }
  ...
}

This ensured responses were in a form that was easy for us to extract the JSON patch from. However, we soon found that our agent would hallucinate invalid JSON patches that referenced keys that didn’t exist in the OpenAPI document. This required augmenting our agent with another tool to verify the validity of these patches by checking if we could apply them.

export class JsonPatchValidator extends DynamicTool {
  static description = `Use this to verify that a given JSON patch is valid.
Always use this tool to check the validity of your final suggestion.
If your suggestion is invalid, use the error message to try to fix it.
Do not return anything this tool says is invalid as your answer.
This tool will return "valid" if the patch is valid, or an error message if it is not.

Example input to this tool:
  [{{ "op": "replace", "path": "/baz", "value": "boo" }}]

Example output: "valid", "error: path /baz does not exist"`;

  constructor(spec: JSON) {
    super({
      name: "json_patch_valid",
      func: async (input) => {
        input = removeQuotes(input);

        try {
          apply_patch(spec, input);
          return "valid";
        } catch (e: any) {
          return `error: ${e}`;
        }
      },
      description: JsonPatchValidator.description,
    });
  }
}

💡For a yaml spec, Speakeasy Suggest takes extra caution by converting it to JSON before applying the patch and converting it back to yaml while preserving the original key ordering.

We’ll discuss several of the tools we equipped our agent within the next section, where we detail the decision-making process of moving forward with a custom agent.

Benchmarking Different Approaches

There were two main approaches we tested — Custom Agent vs. Retrieval Augmented Generation (RAG). In order to not exceed GPT-4’s token limits, we provide a small range of lines surrounding the error from the spec to the LLM prompt. As a result, both approaches need to be capable of enabling the LLM to gather information from the full spec in order to return valid JSON patches. The primary differentiator is how this is achieved:

An agent utilizes tools to enable the LLM to execute custom logic to traverse the spec
In RAG, we use external data to augment our prompts. In our case, this involves the standard method of using a vector store to persist embeddings of the spec, which the LLM can quickly index when trying to answer the prompt.

Agent with Custom Tools

Directly from the langchain docs: “In agents, a language model is used as a reasoning engine to determine which actions to take and in which order.” Each action an agent can take corresponds to one of the tools defined by us that executes a custom function. Since we’re using GPT-4 as our LLM, this takes advantage of OpenAI’s function calling. Our tools take the OpenAPI spec as input and are capable of performing a range of operations on it.

Searching for line numbers that contain a particular string

The LLM may need to locate regions of the spec that are not in close proximity to the validation error but contain a specific key.

WARN validation warn: [line 63] oas3-unused-component - `#/components/schemas/Pets` is potentially unused or has been orphaned

Using model gpt-4-0613
Running agent...

The error message indicates that the schema 'Pets' is potentially unused or has been orphaned. This means that it is not referenced anywhere in the document. To confirm this, I will use the document_text_searcher tool to search for any references to 'Pets' in the document. If there are no references, the schema 'Pets' can be removed from the document. If there are references, they need to be replaced with the correct schema.
Action: document_text_searcher
Action Input: 'Pets'

From the LLM logs, we can see that the document_text_searcher tool searches the document for Pets to see if any usage of this component exists across the schema. The wonderful thing about agents is that the result of this action can be fed as input to other tools before returning a final answer (see get_line_range below).

Retrieving specific line ranges

This is helpful since our validation errors - and the output of other tools - report the offending line number. The LLM uses this to retrieve the region of the spec it needs more information from or where most fixes are likely to be applied.

Following the output of document_text_searcher above, the LLM receives appropriate line numbers to conclude its search and validate the final answer.

The 'Pets' schema is referenced on lines 5 and 99. Line 99 is the definition of the 'Pets' schema itself, so it doesn't count as a usage. I need to check line 5 to see how 'Pets' is used. I will use the get_line_range tool to retrieve lines 1-20 for context.
Action: get_line_range
Action Input: '1-20'

The 'Pets' schema is not used in lines 1-20. It seems that the 'Pets' schema is indeed unused. I will suggest a JSON patch to remove the 'Pets' schema from the document. I will also validate the JSON patch using the json_patch_valid tool.
Action: json_patch_valid
Action Input: [{"op": "remove", "path": "/components/schemas/Pets"}]

The JSON patch is valid. I will now provide the final answer.
Final Answer:
{
  "suggested_fix": "Remove the unused 'Pets' schema from the components.",
  "json_patch": "[{\"op\": \"remove\", \"path\": \"/components/schemas/Pets\"}]",
  "reasoning": "The 'Pets' schema is not referenced anywhere in the document, making it unused and can be safely removed."
}

Resolving $ref definitions

Many OpenAPI specs contain $ref keys that point to definitions living in different parts of the document. The LLM should be able to locate the original definition from this when it needs to use it to suggest a fix. This is useful when we want to suggest an example for a component in the OpenAPI spec.

INFO    validation hint: [line 104] missing-examples - Missing example for component. Consider adding an example

Using model gpt-4-0613
Running agent...

The error message indicates that there is a missing example for a component. Looking at the surrounding context, it seems that the error is on line 162, which corresponds to the "Pets" schema. This schema is an array of "Pet" objects. To fix this error, we need to add an example for the "Pets" schema. The example should be an array of "Pet" objects. We can use the "Pet" schema to create a valid example.

Action: ref_resolver
Action Input: #/components/schemas/Pet

The "Pet" schema requires an "id" and a "name", both of which are strings. An example "Pet" could be {"id": 1, "name": "Fido", "tag": "dog"}. We can use this to create an example for the "Pets" schema, which is an array of "Pet" objects. The JSON patch to add this example would be [{"op": "add", "path": "/components/schemas/Pets/example", "value": [{"id": 1, "name": "Fido", "tag": "dog"}]}]. Let's validate this patch.

Action: json_patch_valid
Action Input: [{"op": "add", "path": "/components/schemas/Pets/example", "value": [{"id": 1, "name": "Fido", "tag": "dog"}]}]

The JSON patch is valid. Therefore, we can suggest this patch as a fix for the error. The patch adds an example to the "Pets" schema, which is an array of "Pet" objects. The example is a valid "Pet" object, as it includes the required "id" and "name" properties.

Final Answer:
{
  "suggested_fix": "Add an example to the 'Pets' schema. The example should be an array of 'Pet' objects. An example 'Pet' object could be {'id': 1, 'name': 'Fido', 'tag': 'dog'}.",
  "json_patch": "[{\"op\": \"add\", \"path\": \"/components/schemas/Pets/example\", \"value\": [{\"id\": 1, \"name\": \"Fido\", \"tag\": \"dog\"}]}]",
  "reasoning": "The error message indicates that there is a missing example for a component. The 'Pets' schema is an array of 'Pet' objects, so the example should also be an array of 'Pet' objects. The 'Pet' schema requires an 'id' and a 'name', so the example 'Pet' object includes these properties."
}

By equipping the agent with the necessary toolkit to explore the spec JSON, we are able to traverse the document without exceeding the TPM (tokens per minute) limit. However, since each initial query to the agent can chain through a sequence of actions before returning a final answer, we wanted to assess another approach that would limit the number of OpenAI calls.

Retrieval Augmented Generation (OpenAPI Spec Embeddings in Chroma)

We use embeddings to store the spec for quick similarity searches without requiring the full contents to be passed into the prompt, enabling us to respect the token limit. Specifically, we used RetrievalQAChain with the OpenAPI spec embedded in Chroma.

Results

We compared the execution time, number of OpenAI calls, and the accuracy of both approaches above. Although RAG seemed to perform fine on **most** simple errors, complex tasks such as moving duplicate inline schemas to shared components seemed impossible. At first, the returned JSON patch for such a task seems reasonable.

INFO {"error":"validation hint: [line 22] duplicate-schemas - Identical inline object schemas found: [line 22] - [line 31] conflicts with [line 107] - [line 116]. Consider moving to a shared component"}

Asking for a Suggestion!

[{"op": "add", "path": "/components/schemas/Error", "value": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "integer", "format": "int32"}, "message": {"type": "string"}}}}, {"op": "replace", "path": "/paths/~1pets/get/parameters/0/schema", "value": {"$ref": "#/components/schemas/Error"}}, {"op": "replace", "path": "/components/schemas/Error", "value": {"$ref": "#/components/schemas/Error"}}]

But upon further review, we found it added the shared component and then swapped out its own schema definition with the $ref, thinking it was one of the duplicate schemas itself despite having a clear line number to check against. Since RAG can’t gather more context via function calls, it would use a similarity search to suggest fixes for same-name fields on the wrong lines. Due to this behavior, this approach wasn’t sufficient for returning JSON patches with the correct paths.

The agent fared much better on all validation errors ranging across a broad span of complexity. Despite the fact that it took 2-3x as long to execute, the agent’s ability to “reason” through a sequence of actions via the execution of custom functions proved to be critical for good suggestion quality. The ability to equip the agent with any new tool we could think of makes it more flexible and future-proof for our use-case than embedding the OpenAPI schema. This is the most important factor in ensuring Suggest is a useful product, as OpenAPI specs vary greatly in shape, purpose, and functionality, much like the tools and people who produce them.

Conclusion

Even after settling on the agent approach, suggestion quality, rate limits, and execution time were all variables that still needed to be addressed. Our team has been tackling these roadblocks by implementing parallelization, passing in additional guidance to the prompt for specific validation errors, and benchmarking various LLMs post fine-tuning.

Want to try it for yourself? Head over to the Speakeasy Suggest docs, or just copy paste this workflow file into your own github repo to get started!

OpenAPI Tips - Query Parameters & Serialization

Tatiana Caciur — Sun, 17 Sep 2023 15:54:28 +0000

The Problem

The OpenAPI spec is best known for descriptions of RESTful APIs, but it’s designed to be capable of describing any HTTP API whether that be REST or something more akin to RPC based calls.

That leads to the spec having a lot of flexibility baked-in: there's a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, the OpenAPI documentation is very ambiguous when it comes to how you should define your API.

That’s why we’re taking the time to eliminate some of the most common ambiguities that you’ll encounter when you build your OpenAPI schema. In this case we’ll be taking a look at how to serialize query parameters in your OpenAPI 3.0.X schema.

Recommended Practices

The OpenAPI spec grants quite a bit of flexibility in defining query parameters for any operation. There are many serialization options and defaults, therefore it’s advisable you define query parameters as strictly as possible in your schema. This will improve your API documentation thereby reducing ambiguity for end-users. In addition, explicit definitions will aid any OpenAPI tooling you may be using to produce artifacts, such as client SDKs.

As an API developer, strict definitions will also give you a more intuitive understanding of each operation’s intended behavior as you iterate on your OpenAPI schema. Concretely, we recommend that you:

Describe your query parameters as explicitly as possible by using OpenAPI defined formats.
Use additional validation attributes as much as possible: mark properties as required, allowReserved, allowEmptyValue, and indicate when fields are nullable.

It’s also important to note that OpenAPI considers a unique operation as a combination of a path and HTTP method, so it is not possible to have multiple operations that only differ by query parameters. In this case, it’s advisable to use unique paths as shown below:

GET /users/findByName?name=anuraag
GET /users/findByRole?role=developer

Query Parameters

Query parameters are criteria which appear at the end of a request URL demarcated by a question mark (?), with different key=value pairs usually separated by ampersands (&). They may be required or optional, and can be specified in an OpenAPI schema by specifying in: query. Consider the following operation for an event catalog:

GET /events?offset=100&limit=50

Query parameters could be defined in the schema as follows:

parameters:
  - in: query
    name: offset
    schema:
      type: integer
    description: The number of items to skip before starting to collect the result set
  - in: query
      name: limit
      schema:
        type: integer
      description: The numbers of items to return

When you’re working with query parameters, it’s important to understand serialization. Let’s explore what serialization is, and the variety of ways the OpenAPI specification supports serialization of query parameters.

Serialization

Serialization is responsible for transforming data into a format that can be used in transit and reconstructed later. For query parameters specifically, this format is the query string for requests of that operation. The serialization method allows us to define this through the use of the following keywords:

style – defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
explode – (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.

OpenAPI supports serialization of arrays and objects in all operation parameters (path, query, header, cookie). The serialization rules are based on a subset of URI template patterns defined by RFC 6570.

From the OpenAPI Swagger documentation, query parameters support the following style values:

form (default) - ampersand-separated values, also known as form-style query expansion. Corresponds to the {?param_name} URI template.
spaceDelimited – space-separated array values. Has effect only for non-exploded arrays (explode: false), that is, the space separates the array values if the array is a single parameter, as in arr=a b c.
pipeDelimited – pipeline-separated array values. Has effect only for non-exploded arrays (explode: false), that is, the pipe separates the array values if the array is a single parameter, as in arr=a|b|c.
deepObject – simple non-nested objects are serialized as paramName[prop1]=value1&paramName[prop2]=value2&.... The behavior for nested objects and arrays is undefined.

The default serialization method is style: form and explode: true. As shown in the GET /events call above, the “?offset=100&limit=50” query string is created with this default serialization when the schema has no references to style or explode. However, we recommend explicitly setting these values, even in the default case, to reap the benefits discussed in “Recommended Practices” above.

Given the path, /events, with a query parameter, id, the query string would be serialized as follows with the above options:

style	explode	Primitive value: id=3	Array id=[1,2,3]	Object id = {"type": "music", "location": "CA"}
form*	true*	/events?id=3	/events?id=1&id=2&id=3	/events?type=music&location=CA
form	false	/events?id=3	/events?id=1,2,3	/events?id=type,music,location,CA
spaceDelimited	true	n/a	/events?id=1&id=2&id=3	n/a
spaceDelimited	false	n/a	/events?id=1%202%203	n/a
pipeDelimited	true	n/a	/events?id=1&id=2&id=3	n/a
pipeDelimited	false	n/a	/events?id=1	2
deepObject	true	n/a	n/a	/events?id[type]=music&id[location]=CA

*Default serialization method

style and explode cover the most common serialization methods, but not all. For more complex scenarios (ex. a JSON-formatted object in the query string), you can use the content keyword and specify the media type that defines the serialization format. The example schema below does exactly that:

parameters:
  - in: query
    name: filter
    # Wrap 'schema' into 'content.'
    content:
      application/json: #media type indicates how to serialize/deserialize parameter content
        schema:
          type: object
          properties:
            type:
              type: string
            location:
              type: string

Additional Attributes

Query parameters can be specified with quite a few additional attributes to further determine their serialization, optionality, and nullability.

AllowReserved

This is the only additional attribute which is specific to query parameters. From the OpenAPI Swagger documentation: The allowReserved keyword specifies whether the reserved characters, defined as :/?#[]@!$&'()*+,;= by RFC 3986, are allowed to be sent as they are as query parameter values or should be percent-encoded. By default, allowReserved is false, and reserved characters are percent-encoded. For example, / is encoded as %2F (or %2f), so that the parameter value, events/event_info.txt, will be sent as events%2Fevent_info.txt. To preserve the / as is, allowReserved would have to be set to true as shown below:

parameters:
  - in: query
    name: path
    required: true
    schema:
      type: string
    allowReserved: true

Required

By default, OpenAPI treats all request parameters as optional. You can add required: true to mark a parameter as required.

Default

Use the default keyword in the parameter schema to specify the default value for an optional parameter. The default value is the one that the server uses if the client does not supply the parameter value in the request. The value type must be the same as the parameter’s data type.

Consider a simple example, where default used with paging parameters allows these 2 calls from the client to be equivalent:

GET /events
GET /events?offset=0&limit=100

This would be specified in the schema like so:

- in: query
  name: offset
  schema:
    type: integer
    default: 0
  description: The number of items to skip before starting to collect the result set
- in: query
  name: limit
  schema:
    type: integer
    default: 100
  description: The numbers of items to return

The default keyword should not be used with required values. If a parameter is required, the client must always send it and therefore override the default.

Enum and Constant Parameters

You can restrict a parameter to a fixed set of values by adding the enum to the parameter’s schema. The enum values must be the same type as the parameter data type.

A constant parameter can then be defined as a required parameter with only one possible value as shown below:

parameters:
  - in: query
    name: eventName
    required: true
    schema:
      type: string
      enum:
        - coachella

The enum property specifies possible values, and in this example, only one value can be used.

It’s important to note a constant parameter is not the same as the default parameter value. A constant parameter is always sent by the client, whereas the default value is something that the server uses if the parameter is not sent by the client.

Empty-Valued and Nullable

Query string parameters may only have a name and no value, like so:

GET /events?metadata

Use allowEmptyValue to describe such parameters:

parameters:
  - in: query
    name: metadata
    required: true
    schema:
      type: boolean
    allowEmptyValue: true

The OpenAPI spec also supports nullable in schemas, allowing operation parameters to have the null value when nullable: true. This simply means the parameter value can be null, and is not the same as an empty-valued or optional parameter.

Deprecated

Use deprecated: true to mark a parameter as deprecated.

Common Parameters Across Methods in Same Path

Parameters may be defined once to be used in multiple methods/paths in an OpenAPI schema. Parameters shared by all operations of a path can be defined on the path level instead of the operation level. These path-level parameters are inherited by all operations (GET/PUT/PATCH/DELETE) of that path. An example is shown below(manipulating the same resource in different ways is a good use case here):

paths:
  /events:
    parameters:
      - in: query
        name: filter
        content:
          application/json:
            schema:
              type: object
                properties:
                  type:
                    type: string
                  location:
                    type: string
  get:
    summary: Gets an event by type and location
    ...
  patch:
    summary: Updates the newest existing event with the specified type and location
    ...
  delete:

Any extra parameters defined at the operation level are used in addition to path-level parameters. Specific path-level parameters may also be overridden on the operation level, but cannot be removed.

Common Parameters Across Multiple Paths

Parameters can also be shared across multiple paths. Pagination is a good candidate for this:

components:
  parameters:
    offsetParam:
      - in: query
        name: offset
        required: false
        schema:
          type: integer
        minimum: 0
        default: 0
        description: The number of items to skip before collecting the result set.
    limitParam:
      - in: query
        name: limit
        required: false
        schema:
          type: integer
        minimum: 1
        default: 10
        description: The number of items to return.
paths:
  /events:
    get:
      summary: Gets a list of events
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
  /locations:
    get:
      summary: Gets a list of locations
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
    ...

Note the above parameters defined in components are simply global definitions that can be handily referenced. They are not necessarily applied to all methods of an operation.

OpenAPI Tips - How to Handle Auth

Tatiana Caciur — Thu, 24 Aug 2023 17:48:14 +0000

The Problem

The OpenAPI spec is best known for descriptions of RESTful APIs, but it’s designed to be capable of describing any HTTP API whether that be REST or something more akin to RPC based calls. That leads to the spec having a lot of flexibility baked-in; there's a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, the OpenAPI documentation is very ambiguous when it comes to how you should define your API. That’s why we’d like to take the time to eliminate some of the most common ambiguities that you’ll encounter when you build your OpenAPI spec. In this case we’ll be taking a look at how to correctly configure auth in your OpenAPI spec.

What Authentication mechanisms are available?

OpenAPI supports a number of different options for API authentication, which can be daunting when first starting out. Before we give our thoughts on the different methods, it’s worth highlighting that regardless of the method of authentication you choose, you should pair it with TLS. TLS encrypts the messages to and from your API, to protect you and your users from attack. Learn more about setting up TLS here. Some of the common types of authentication are listed below:

apiKey: This is the most common form of authentication for machine-to-machine (M2M) APIs and supports passing a pre-shared secret in a number of different ways i.e. either via the Authorization header (or another custom header), as a query parameter, or via a cookie. While this is probably the most commonly used mechanism, it is generally one of the least secure. This is especially true if the key is passed outside of headers or cookies (i.e. via query params as various logging mechanisms normally store query param information). The biggest security flaw is that most pre-shared secrets are long lived and if intercepted can be used until they are either revoked or expire (generally in a number of months or years). This risk is normally tolerated for M2M applications as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low when compared to a key from a user’s device traveling on a public network.
basic: This is a simple authentication mechanism baked into the HTTP protocol. It supports sending an Authorization header containing an encoded username and password. While this can be a relatively simple mechanism to get started with, if used incorrectly can risk leaking easy to decode passwords. It also shares a lot of the downsides of apiKeys below.
bearer: This scheme allows the passing of a token (most commonly a JWT) in the Authorization header. This is generally used for short lived tokens that are granted to the users of your API through an additional login mechanism. Using a JWT allows for the storage of additional metadata within the token which can be helpful for some use cases, such as storing scopes for permissions models.
oauth2: A popular open authentication mechanism that supports an authentication flow that allows servers to authenticate on behalf of a user or organization. While more generally used for authenticating clients and end-users it is quite often used in machine-to-machine applications as well, but is less popular due to the added complexity of the authentication flows. OAuth2 is considered more secure than other mechanisms due to its granted privileges through short lived tokens, that limit damage from intercepting the tokens.
openIdConnect: Is an authentication mechanism built on top of OAuth2 that allows obtaining identity information about the authenticating user via JWTs.

Global Authentication vs Endpoint Authentication

The OpenAPI specification allows you to describe all the above authentication mechanisms and more from the HTTP Authentication Scheme Registry.

Describing security in your OpenAPI document is then done through 1 of 2 different options:

Global security: the security you describe is available for all operations in your document.
Per operation security: when described it overrides any global level security described.

Here is an example of describing security in the ways mentioned above:

openapi: 3.0.3
info:
  title: Example Security Definitions
  version: 1.0.0
servers:
  - url: http://api.prod.speakeasyapi.dev
# Here we are describing the Global security schemes used by the operations in this document
# This is a list of security schemes names defined in the components section
security:
  - APIKey: []
components:
  # The definition of the used security schemes
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /test:
    get:
      # The security schemes defined here will override the global security schemes for this operation
      security:
        - Bearer: []
      responses:
        200:
          description: OK
    # This operation used the global security schemes defined as it doesn't provide its own
    delete:
      responses:
        200:
          description: OK

The important parts of the above example are the security and securitySchemes sections. We will go into some details about how they are defined and the options available.

How To Describe Security

The security section is a list (actually a list of key-value pairs, but we will talk a bit more about that later) of security schemes that can be used to authenticate all operations or a particular operation (depending on the scope of the security list).

Below is an example of a number of different ways you can use the security section of your document:

# The below example shows a single mandatory scheme needed for the API
security:
  - APIKey: []
# The below example shows that one of the below schemes is required for the API 
security:
  - APIKey: []
  - Bearer: []
# The below example shows there is no security required for the API
# this is equivalent to not having a security section at all at the Global scope
# or disabling security at the per operation level
security: []
# The below example shows that security is optional for the API
# this may be used if an API provides additional functionality when authenticated
security: 
  - APIKey: []
  - {}
# The below example shows that certain scopes are required by the OAuth token used
# to authenticate the API
security:
  - OAuth:
    - read
    - write

The items in the list are key-value pairs with a name or key of a security scheme defined in the components section. We recommend giving them a boring name that explains what they are.

The values are an array of scopes used only by the oauth2 and openIdConnect type schemes, and define what scopes are needed for the API.

When used as shown above it provides a list of available schemes that can be used, with the end-user of the API being able to choose one of the available schemes to use to authenticate.

If more than one scheme is required to authenticate an API, then that is where additional pairs in the key-value pairs come in. See the example below:

# The below example shows 2 options for an end user to choose, as long as they use one or the other
# they will be able to access the API
security:
  - APIKey: []
  - Bearer: []
# The example below differs as it is a single option with multiple schemes
# Both the APIKey and SigningKey need to be used together to access the API
security:
  - APIKey: []
    SigningKey: []
# The example below shows multiple options for an end user to chose
# with one of them requiring the use of multiple schemes
security:
  - APIKey: []
    SigningKey: []
  - Bearer: []

Combining schemes like above give you the option to define AND/OR type functionality when it comes to the requirements of your API.

How To Describe Security Schemes

securitySchemes are the actual details of the options provided in the security sections of your document. The security schemes are components that are defined with the components section of your document. Below is an example of the 5 types of security schemes described above and how they are defined:

...
components:
  schemas:
    ...
  responses:
    ...
  # The definition of the used security schemes
  securitySchemes:
    BasicAuth: # An arbitrary scheme name, we recommend something descriptive
      type: http
      scheme: basic
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT # Optional token format
    APIKey:
      type: apiKey
      in: header # or query/cookie
      name: X-API-Key
    OAuth:
      type: oauth2
      flows: # Many different flows are available - https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
        implicit:
          authorizationUrl: https://test.com/oauth/authorize
          scopes:
            read: Grants read access
            write: Grants write access
    OpenIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://test.com/.well-known/openid-configuration

Best Practices

I generally recommend considering developer experience and weighing this up against the security requirements of your API. Consider its use cases such as will it be called from another server? A client? Or a combination of both. Based on your needs then try to describe your security requirements in your OpenAPI document as simply as possible, if you can avoid multiple options or too many per operation differences then it will generally require less friction for your end-user to get up and running and start using your API. This is the main reason we still see pre-shared secrets (described by the apiKey type above) being the most ubiquitous option amongst APIs today, but if not managed correctly it can be one of the least secure options available.

DEV Community: Tatiana Caciur

Create Production-Ready SDKs With gRPC Gateway

An Overview of gRPC Gateway

OpenAPI Versions

The Protobuf to REST SDK Pipeline

Step-by-Step Tutorial: From Protobuf to OpenAPI to an SDK

Check Out the Example Repository

Install Go

Install Buf

Install Buf Modules

Install protoc-gen-go

Install Go Requirements

Generate the Go Code

Generate the OpenAPI Schema

Convert the OpenAPI Schema to OpenAPI 3.0

Create an SDK With Speakeasy

How To Customize the SDK

Meet the Speakeasy Bar Protobuf Service

Add API Information to the Service

Add Descriptions and Examples to Components

Customize the OperationId

Add Descriptions and Tags to Methods

Add OpenAPI Extensions

Add Tag Descriptions

Example Protobuf Definition and SDK Generator

Create Production-Ready SDKs for tRPC

The SDK Creation Pipeline

Requirements

Supported OpenAPI Versions

Why Speakeasy and tRPC?

How To Generate an OpenAPI Spec With tRPC

Add trpc-openapi to a Project

How To Improve the OpenAPI Info Section

Improving the OpenAPI Paths

Expanding the Procedure’s Input and Output Schemas

OpenAPI Model Schemas in tRPC

Adding a Summary, Description, Examples, and Tags to a Procedure

Add Metadata to Tags

Add Speakeasy Extensions to Methods

Add Retries to an SDK With x-speakeasy-retries

Adding Global Retries and Retries per Endpoint

How To Create an SDK Based on the OpenAPI Spec

Add SDK Creation to GitHub Actions

Create Production-Ready SDKs with Goa

Generate SDKs with Goa

Is This Tutorial Right for You?

Prerequisites

Introduction to Goa

Other Go OpenAPI Frameworks

Is this related to tsoa?

Create the API Specification in Goa

Download the Example Repository

Google Protocol Buffers

Set Up Go

Review the Goa Design File

Encapsulate With References

Rename With Custom operationIds

Group Operations With Tags

Customize With Extensions

Retry Calling the Server

Generate the API Code With Goa

Explore the Generated Files

Run the Server and CLI

Create SDKs With Speakeasy

Set Up the Speakeasy CLI

Build an SDK

Explore the Generated Files

Call Your Service With the SDK

Next Steps

Get Help With Advanced Goa

Use Speakeasy Customizations

How to Create an OpenAPI Spec & SDKs with tsoa

Integrate tsoa with Speakeasy

The SDK Generation Pipeline

How to Generate an OpenAPI Spec with tsoa

Generating an OpenAPI Spec Using the tsoa CLI

Programmatically Generate an OpenAPI Spec Using tsoa

Supported OpenAPI Versions

How tsoa Generates OpenAPI info

Set OpenAPI info in package.json

Add Retries to an SDK With `x-speakeasy-retries`

How tsoa Generates OpenAPI `info`

Set OpenAPI `info` in `package.json`

Customizing OpenAPI `operationId` Using tsoa

Using the `@OperationId` Decorator

Using the Default tsoa `operationId` Generator

Creating a Custom `operationId` Template

Add Retries to Your SDK With `x-speakeasy-retries`

What is `oneOf`?

What is `allOf`?

What is `anyOf`?

Add Retries to Your SDK With `x-speakeasy-retries`