Sourced*

Frameworks

Generate an SDK from Spring Boot with springdoc-openapi

· 6 min read · Sourced

  • spring-boot
  • java
  • openapi
  • sdk
  • codegen

Spring Boot doesn't ship OpenAPI output on its own, but springdoc-openapi gets you there with a single dependency and zero extra code: add it, boot the app, and a full spec is live at /v3/api-docs. That's the whole setup — no annotations required for a working baseline. From there, a Spring OpenAPI SDK is the same two-step problem as any other framework: get a clean spec out, then run it through a generator or a hosted pipeline like Sourced.

Getting an OpenAPI spec out of Spring Boot with springdoc-openapi

Add the starter that matches your stack. For a standard servlet (WebMvc) app on Spring Boot 3:

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.x.x</version>
</dependency>

Or with Gradle:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.x.x'

Springdoc's own docs are explicit that springdoc-openapi v3 targets Spring Boot 4 (Java 17+, Jakarta EE 9), while v2 is the line for Spring Boot 3 — pick the major version that matches your Spring Boot version, not just the latest tag. A WebFlux (reactive) variant of the same starter exists if you're not on the servlet stack.

That's it — no controller changes needed. On next boot:

Endpoint Format Notes
/v3/api-docs JSON The full OpenAPI document, generated at runtime from your controllers
/v3/api-docs.yaml YAML Same document, YAML-serialized
/swagger-ui.html HTML Interactive Swagger UI, reading the same document

Common application.properties overrides:

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false

To pull the file for a generator, hit the running app: curl localhost:8080/v3/api-docs -o openapi.json.

The gotcha: the OpenAPI version you get isn't automatic

springdoc-openapi can emit either OpenAPI 3.0 or 3.1 from the same annotations, controlled by the springdoc.api-docs.version property. Don't assume which one you're on — check it explicitly, especially if a downstream generator or docs tool cares about the difference between 3.0 and 3.1's nullable handling or JSON Schema alignment. See OpenAPI 3.1 vs 3.0: what to use for what actually changes, and validate the emitted document rather than assuming a version.

The gotcha: default exception responses don't type themselves

springdoc documents whatever response types your controller methods declare — usually via ResponseEntity<T> return types or @ApiResponse annotations. What it can't infer on its own is the shape of errors thrown from a global @ControllerAdvice or @ExceptionHandler that isn't wired into a specific endpoint's documented responses. Left undocumented, that error shape either doesn't appear in the spec at all, or lands in a catch-all default response — and a responses.default schema is exactly what real generated TypeScript clients silently drop from return types. See fix weak generated return types from OpenAPI's default response for how that failure looks downstream, and document your error DTO explicitly with @ApiResponse(responseCode = "default", ...) or per-status-code annotations on each operation.

From a Spring Boot spec to hosted docs and typed SDKs

Once /v3/api-docs reflects the version and error shapes you intend, turning it into an installable SDK is a separate step. With Sourced:

  1. Point Sourced at your repo or the live endpoint. Connect from GitHub, or paste the /v3/api-docs output directly into a new project.
  2. Preview the TypeScript and Python SDKs. Sourced renders both before anything publishes — method names, typed models, error classes — so a dropped default-response type is visible in the preview, not a customer's catch block.
  3. Get hosted docs and an llms.txt from the same spec. No separate docs deploy — the hosted docs preview and llms.txt come from the same pass as the SDKs.
  4. Publish on your schedule. Free unlimited previews and up to 2 hosted noindex docs review sites and one hosted MCP server, no credit card, cover steps 1-3.

Comparison: springdoc-openapi vs. a full SDK pipeline

Need springdoc-openapi gives you What it doesn't give you
A generated OpenAPI spec Yes, zero-config from your controllers Nothing — this part is real and free
OpenAPI 3.0 or 3.1 output Yes, via springdoc.api-docs.version Nothing to add — just check which one you're on
Interactive API browsing Swagger UI at /swagger-ui.html A hosted docs site for customers
A typed client SDK Nothing built in Generated TypeScript or Python SDK
A diff before a breaking release Nothing built in A compatibility report
Agent-readable docs Nothing built in llms.txt derived from the spec

OSS generators for other languages

Sourced's generated SDKs focus on TypeScript and Python today — the two ecosystems where teams publish first. That's not Java, so for the SDK itself, a clean /v3/api-docs output works with the standard per-language OpenAPI Generator ecosystem — Java (a natural fit alongside a Java backend), Kotlin, Go, Ruby, PHP, C#, Rust, and Swift all have their own walkthroughs. The five-minute generate-an-SDK guide covers running a local generator against any spec, springdoc's included. Sourced still has a role on that same /v3/api-docs file: hosted docs, llms.txt, and spec validation, independent of which language generates the client.

Other backend frameworks with their own spec-extraction paths: FastAPI, NestJS, Express, Django, Rails, Laravel, and .NET.

Honest scope: when springdoc-openapi alone is enough

If your Spring Boot service only has internal Java consumers, /swagger-ui.html plus a shared RestTemplate or WebClient wrapper is a reasonable stopping point — you already own the DTOs on both ends, and a codegen pipeline adds a maintenance surface you might not need. springdoc-openapi's zero-config default is also a double-edged sword: it documents whatever your controllers actually return, including internal fields you didn't mean to expose, so review the generated /v3/api-docs before you publish it anywhere public. Reach for full SDK generation once you have external customers, a second language to support, or a docs site that needs to exist independently of your Swagger UI mount.

FAQ

Does Spring Boot generate OpenAPI automatically?

Not without a dependency. Plain Spring Boot has no built-in OpenAPI output. Add springdoc-openapi-starter-webmvc-ui (or the WebFlux equivalent) and a full spec appears at /v3/api-docs on the next boot, with no annotations required for a working baseline.

What's the default OpenAPI spec URL in Spring Boot?

/v3/api-docs for JSON, /v3/api-docs.yaml for YAML — both configurable via the springdoc.api-docs.path property. Swagger UI reads the same document at /swagger-ui.html by default.

Does springdoc-openapi support OpenAPI 3.1?

Yes — it can emit either OpenAPI 3.0 or 3.1 from the same code, controlled by the springdoc.api-docs.version property. Check which one is configured rather than assuming; see OpenAPI 3.1 vs 3.0 for what the difference means for codegen.

Which springdoc-openapi version do I need for my Spring Boot version?

springdoc-openapi v2.x targets Spring Boot 3 (Java 17+). springdoc-openapi v3.x targets Spring Boot 4 (Java 17+, Jakarta EE 9). The dependency's major version needs to match your Spring Boot major version.

Why is my error response typed as any in the generated SDK?

Most likely your @ControllerAdvice/@ExceptionHandler error shape isn't documented per-operation, so it either falls into an undocumented gap or a catch-all default response — and generators typically drop default-only response schemas from the typed return value. See fix weak generated return types from OpenAPI's default response for the exact failure and the annotation fix.

Can I generate the spec without a running Spring Boot app?

Not with the runtime /v3/api-docs endpoint — it's generated on request from live application context. springdoc-openapi also offers a Maven/Gradle plugin (springdoc-openapi-maven-plugin / springdoc-openapi-gradle-plugin) that boots the app during the build and writes the spec to a file, if you need it without hitting a running server manually.

Ship it

Once /v3/api-docs reflects the OpenAPI version and error types you intend, you have a real Spring OpenAPI SDK source to work with. Start free on Sourced to preview a TypeScript and Python SDK plus hosted docs from that spec in one pass, or run it through the OpenAPI validator first to catch version and response-typing gaps before you generate anything.