# Does CommonGrants Generate OpenAPI Specifications?

> Yes CommonGrants generates OpenAPI 3.0 specifications. Learn about its TypeSpec compilation pipeline and FastAPI helper script for automated spec generation.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: deep-dive
- Published: 2026-03-03

---

**CommonGrants generates OpenAPI 3.0 specifications through two primary mechanisms: a TypeSpec compilation pipeline using the `@typespec/openapi3` emitter, and a FastAPI helper script that produces specs from running implementations.**

The `hhs/simpler-grants-protocol` repository automates OpenAPI generation to ensure API consistency across different CommonGrants implementations. Developers can produce specifications directly from protocol definitions or extract them from live FastAPI applications.

## How CommonGrants Generates OpenAPI Specifications

### TypeSpec Compilation Pipeline

The primary generation method uses **TypeSpec** with the `@typespec/openapi3` emitter. According to the source code in [`website/tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/tspconfig.yaml), this emitter is configured to compile TypeSpec definitions into OpenAPI 3.0 documents.

The build process runs through the `typespec:openapi` script defined in [`website/package.json`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/package.json). This script compiles `website/src/specs/main.tsp`—the minimal entry point that imports the core library—and copies the generated output to `website/public/openapi/`. The resulting files include versioned specifications such as [`openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.0.1.0.yaml).

### FastAPI Runtime Generation

For Python implementations, the repository provides a runtime generation utility. The file [`templates/fast-api/src/common_grants/scripts/generate_openapi.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/fast-api/src/common_grants/scripts/generate_openapi.py) uses FastAPI's native `get_openapi` utility to introspect a running application and export its specification.

This approach allows developers to generate specs that reflect the actual runtime state of their API, including any dynamic routes or configuration applied at startup.

## Step-by-Step: Generating Your OpenAPI Spec

### Method 1: Compile from TypeSpec Definitions

Run the TypeSpec compiler from the `website` directory to generate the specification from protocol definitions:

```bash

# Compile main.tsp and output to public/openapi/

pnpm typespec:openapi

# View the generated specification for version 0.1.0

cat public/openapi/openapi.0.1.0.yaml

```

### Method 2: Export from a FastAPI Implementation

Use the helper script to extract the OpenAPI spec from a running FastAPI project:

```bash

# Generate the specification and redirect to a file

python src/common_grants/scripts/generate_openapi.py > openapi.yaml

# Validate the generated spec using the CommonGrants CLI

cg check spec openapi.yaml

```

### Method 3: Serve with Swagger UI

The Astro-based documentation site automatically serves generated specifications with interactive documentation:

```bash

# Start the development server to host /openapi/* endpoints

npm run dev

```

The server uses `swagger-ui-react` to render the UI for the specifications stored in `website/public/openapi/`.

## Key Files and Configuration

- **[`website/tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/tspconfig.yaml)** — Configures TypeSpec emitters, including the `@typespec/openapi3` emitter responsible for OpenAPI generation.

- **[`website/package.json`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/package.json)** — Contains the `typespec:openapi` npm script that orchestrates compilation and file copying to the public directory.

- **`website/src/specs/main.tsp`** — The TypeSpec entry point that imports the core CommonGrants library and serves as the source of the generated specification.

- **[`website/public/openapi/openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/public/openapi/openapi.0.1.0.yaml)** — Example of a compiled OpenAPI 3.0 document available in the repository.

- **[`templates/fast-api/src/common_grants/scripts/generate_openapi.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/fast-api/src/common_grants/scripts/generate_openapi.py)** — FastAPI helper script that builds an OpenAPI specification at runtime using the `get_openapi` function.

## Summary

- **CommonGrants generates OpenAPI 3.0 specifications** via TypeSpec compilation and FastAPI runtime extraction.
- The **TypeSpec pipeline** uses `@typespec/openapi3` configured in [`tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/tspconfig.yaml) to compile `main.tsp` into YAML specifications.
- The **FastAPI helper** in [`generate_openapi.py`](https://github.com/hhs/simpler-grants-protocol/blob/main/generate_openapi.py) creates specs from running applications using FastAPI's native utilities.
- Generated files are stored in `website/public/openapi/` and served automatically through the documentation site's Swagger UI integration.

## Frequently Asked Questions

### Does CommonGrants support OpenAPI 3.0 or 3.1?

CommonGrants currently generates **OpenAPI 3.0** specifications through the `@typespec/openapi3` emitter. The configuration in [`website/tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/tspconfig.yaml) targets the 3.0 specification version, as evidenced by the generated [`openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.0.1.0.yaml) file structure.

### Can I generate OpenAPI specs without using TypeSpec?

Yes. If you implement CommonGrants using the FastAPI template, you can generate specifications without TypeSpec by running `python src/common_grants/scripts/generate_openapi.py`. This script uses FastAPI's `get_openapi` utility to introspect your running application and output a valid OpenAPI document.

### Where are the generated OpenAPI files stored in the repository?

Compiled TypeSpec output is stored in `website/public/openapi/`, with specific versions named according to their release (e.g., [`openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.0.1.0.yaml)). The `typespec:openapi` build script in [`website/package.json`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/package.json) automatically copies files from the TypeSpec output directory to this public folder.

### How do I validate a generated OpenAPI specification?

Use the CommonGrants CLI `cg check spec` command to validate your generated files. After producing a spec with either the TypeSpec pipeline or the FastAPI script, run `cg check spec openapi.yaml` to verify compliance with the CommonGrants protocol requirements.