Does CommonGrants Generate OpenAPI Specifications?

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, 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. 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.

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 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:

# 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:

# 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:

# 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 — Configures TypeSpec emitters, including the @typespec/openapi3 emitter responsible for OpenAPI generation.

• 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 — Example of a compiled OpenAPI 3.0 document available in the repository.

• 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 to compile main.tsp into YAML specifications.
• The FastAPI helper in 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 targets the 3.0 specification version, as evidenced by the generated 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). The typespec:openapi build script in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}