Skip to content

OpenAPI Specs

Dezycro uses your service's OpenAPI specification as the source of truth for what your API actually does. The richer the spec, the better Dezycro's generated tests, journey plans, and verifier runs.

This page covers:

  1. Generating an OpenAPI spec from your codebase
  2. Getting that spec into Dezycro

Why Dezycro needs a spec

When you run /dezycro:publish-spec — or push a spec through the CI ingest action — Dezycro:

  • Resolves your declared endpoints, request/response schemas, and auth requirements
  • Generates Journey Execution Plans (JEPs) that string endpoints into realistic user journeys
  • Drives the verifier with assertions tied to your real schema
  • Improves the relevance of PRD/TRD generation when your spec describes real product behavior, not just CRUD

A weak or missing spec degrades all of the above. The cheapest, biggest improvement most teams can make is a complete OpenAPI document.

Generating a spec

You almost never want to write OpenAPI by hand. Pick the generator native to your framework and let it derive the spec from the code that handles requests. Quarkus + SmallRye is what we run internally and what we recommend.

We use SmallRye OpenAPI — exposed in Quarkus via the quarkus-smallrye-openapi extension — and recommend it.

Add the extension:

pom.xml
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

Or with Gradle:

build.gradle.kts
implementation("io.quarkus:quarkus-smallrye-openapi")

That's it for the minimum. SmallRye introspects your Jakarta REST (@Path / @GET / @POST / @Produces …) endpoints and serves a complete spec at:

  • http://localhost:8080/q/openapi — YAML
  • http://localhost:8080/q/openapi?format=json — JSON

Configure the info block in application.properties:

quarkus.smallrye-openapi.info-title=My API
quarkus.smallrye-openapi.info-version=1.0.0
quarkus.smallrye-openapi.info-description=Public surface of the Foo service.
quarkus.smallrye-openapi.servers=https://api.example.com

Annotate where defaults aren't enough. Most endpoints don't need any annotations; SmallRye reads the JAX-RS method signature. Add annotations only where you want more detail:

@POST
@Path("/widgets")
@Operation(
    summary = "Create a widget",
    description = "Idempotent on the (name, scope) pair."
)
@APIResponse(responseCode = "201", description = "Widget created")
@APIResponse(responseCode = "409", description = "Widget already exists")
public Response create(@Valid CreateWidgetRequest body) { ... }

Verify it locally:

curl http://localhost:8080/q/openapi?format=json | jq '.paths | keys' | head

You should see every endpoint your service exposes.

Official docs:

Use springdoc-openapi.

pom.xml
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.0</version>
</dependency>

Spec is served at /v3/api-docs (JSON) and /v3/api-docs.yaml.

Official docs:

FastAPI generates a spec automatically at /openapi.json. No setup needed beyond declaring your routes with type hints and Pydantic models.

Official docs:

Use drf-spectacular.

settings.py
INSTALLED_APPS += ["drf_spectacular"]
REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

Spec is served at /api/schema/ (configurable).

Official docs:

We don't have a single recommendation — both tsoa (TypeScript, code-first) and swagger-jsdoc (JSDoc-driven) work. Whichever you pick, expose the resulting JSON at a stable URL.

Official docs:

Getting the spec into Dezycro

Once your service serves a spec, there are two paths into Dezycro depending on who's driving:

Interactive — /dezycro:publish-spec

From Claude Code inside the repo:

/dezycro:publish-spec

This auto-detects the spec endpoint (e.g. /q/openapi, /v3/api-docs, /openapi.json), optionally filters to the active feature's endpoints, uploads to Dezycro, and triggers JEP generation. See the Claude Code commands reference.

Automated — CI ingest action

For backends that publish a new spec on every release, use the ingest-to-dezycro action in your build pipeline with source-type: OPENAPI. A full example is in the CI integration guide.

Spec quality checklist

A spec that maximizes what Dezycro can do for you:

  • [ ] Every endpoint your service exposes is listed — including auth, health, admin routes
  • [ ] Request and response bodies have schemas, not free-form object
  • [ ] Path/query/header parameters declare types and constraints (format, minimum, maxLength, enum)
  • [ ] All non-2xx responses are documented (401, 403, 404, 409, 422, 5xx)
  • [ ] Security schemes are declared (bearerAuth, apiKey, OAuth flows) and applied per-endpoint
  • [ ] info.title and info.version are meaningful — Dezycro uses them as labels

You don't have to hit all of these on day one. Even a bare-bones auto-generated spec is a big upgrade over no spec at all.