The springdoc demo repository is a matrix of Spring Boot 4 OpenAPI starting points

Twelve modules, one link per stack combination

The repository is a set of demo applications rather than a single project, and the README is a list of links to the running demos on demos.springdoc.org.

The list starts with the two obvious pairs. There is a Spring Boot 4 Web MVC demo with OpenAPI 3 and a Spring Boot 4 WebFlux demo with OpenAPI 3, and the WebFlux one links straight to the swagger-ui page of the running application. Then the same two stacks appear again with Scalar as the documentation view, a Web MVC variant and a WebFlux variant, each linking to the scalar path.

So the matrix is already two axes wide at the top: the web stack on one side, the documentation renderer on the other. The remaining entries widen it. There is a WebFlux demo with functional endpoints, a demo combining Spring Boot 4 with Spring HATEOAS, two Spring Cloud Function demos for Web MVC and WebFlux, a Spring Cloud Gateway demo that lives under a demo-microservices directory, a Spring AI MCP Server demo that links to an mcp-ui path, and an MCP Authorization Server demo that links into a .well-known path with its source code in a separate module.

That last pair is the interesting one. An MCP server and an MCP authorization server are two different things to get right, and the project ships both as separate running demos with a link into the OAuth well-known path, which tells you the authorization side is a real deployment concern rather than a stub.

The module names are the documentation

The top level of the repository is a directory per demo, and the names map one to one onto the links in the README.

There is demo-spring-boot-webmvc and demo-spring-boot-webflux for the two base stacks, demo-spring-boot-webmvc-scalar and demo-spring-boot-webflux-scalar for the Scalar variants, and demo-spring-boot-webflux-functional for the functional endpoints demo. The HATEOAS one is demo-spring-hateoas. The Spring Cloud Function demos sit together in demo-spring-cloud-function, the Cloud Gateway and microservices work is in demo-microservices, and the MCP applications are demo-spring-boot-mcp and demo-spring-boot-mcp-authorization-server.

There are also modules that the README does not link, which is worth noticing. demo-book-service, demo-person-service, demo-oauth2 and demo-spring-data-rest are present in the tree without a corresponding entry in the link list. Those look like the supporting services for the demos that need a second application to talk to, since a person service and a book service are the sort of thing a Cloud Gateway or Cloud Function example needs on the other end. The documentation simply does not surface them, which is a small reminder that the README is an index of the interesting endpoints rather than a complete inventory.

The build is a single Maven reactor. There is a pom.xml at the root, a settings.xml, and a .java-version file, which pins the JDK the modules are built against. The .github directory holds the demos workflow whose badge appears at the top of the README, so the running demos are verified in continuous integration rather than deployed by hand.

Swagger UI and Scalar side by side, not one or the other

The most useful thing in this repository is the pair of documentation renderers run over the same kind of application.

The base demos link to swagger-ui.html, which is the classic Swagger UI page, and the Scalar demos link to a scalar path instead. Scalar is a different OpenAPI reference renderer, and seeing the same generated description rendered by both makes one thing obvious: the documentation output is produced by springdoc from your annotations and your code, and the renderer is a separate, replaceable layer on top of it.

That separation is the practical lesson for anyone integrating this into a real service. If you generate the OpenAPI description, you can present it with whichever tool your consumers prefer, and you can change your mind later without touching the generation side. A project that only ever demonstrated Swagger UI would hide that choice, because you would not know whether the coupling was in the generation or in the view.

The functional endpoints demo is the other one to look at if you use WebFlux. Functional endpoints are a different style of controller, where routes are declared as functions rather than as annotated methods, and the question of whether the OpenAPI description still comes out right is exactly the kind of thing a demo answers better than documentation does.

The HATEOAS demo covers the case where your responses are not plain DTOs but objects with a links section, which changes what a generated schema can describe.

MCP and OAuth2 demos point at a moving target

The two most recent additions to the list are the ones with the least settled conventions, and the repository shows them as running applications rather than snippets.

The Spring AI MCP Server demo links to an mcp-ui path under the demo-spring-boot-mcp module, and the MCP Authorization Server demo links to a .well-known/oauth-authorization-server path with a separate source module. The .well-known path is the standard location where an OAuth authorization server advertises its metadata, so the demo is a real authorization server with real metadata, not a mock.

That pairing is the sensible way to learn this corner. An MCP client needs a server, and the server needs an authorization server, and each of those is a moving part with its own configuration. Having all three pieces running at once on the demos site means you can look at how they are wired rather than reconstructing it from three separate blog posts.

The Cloud Gateway demo, which lives under demo-microservices, plays the same role for the API gateway side of the OpenAPI story. A gateway aggregates services, and what it publishes as a single API description is not simply the union of the descriptions behind it.

The demo-oauth2 module in the tree is the piece that connects these, an OAuth2 protected service that the other demos can call.

What the repository does not tell you

The documentation here is thin, and the gaps are predictable for a demo repository.

There are no build or run instructions in the README. It links to the running demos and to the springdoc.org homepage, and that is the whole text. There is no statement of the springdoc version the modules use, no list of the dependencies added to each pom, and no mention of the annotation or configuration the modules rely on. If you want to know how the OpenAPI description is produced, you read the module source and the springdoc.org documentation, and those are two different places.

The README also does not explain how the demos are deployed. There is a workflow file for the demos, but the hosting arrangement for demos.springdoc.org is not described, so the pipeline from a merged pull request to a running demo is invisible from the repository.

The .java-version file and the settings.xml hint that the build has environment specific configuration, since a settings.xml at the root of a demo repository is usually there to point Maven at a mirror or a repository manager.

None of this makes the repository less useful, because the running demos are the documentation. But it does mean the repository answers the question what does this look like working, and it does not answer the question how do I configure this in my own project, which is the question most people arrive with.

Who is behind the demos, and what to take from them

The repository carries an Apache-2.0 LICENSE file, publishes no GitHub releases, and the last push was on 2026-09-06, so the demos move with the code rather than being versioned artefacts.

The README includes a thank you note to JetBrains for supporting the springdoc-openapi project, with a logo image and a link to their site. That is a sponsorship acknowledgement for the parent project rather than for the demos, and it is worth knowing that the demos exist to demonstrate springdoc rather than to be a standalone product with its own roadmap.

There is a SUPPORT.md file at the root, which the README does not link but which tells you where support questions are meant to go, and the springdoc.org homepage is the documentation site for the project as a whole.

For a team, the right way to use this repository is as a reference. Start the module that matches your stack, read how it is wired, and take the parts you need into your own application, where you will be responsible for the versions. The demos give you a working configuration you can copy; they do not give you something to depend on, and with no releases published there is nothing to depend on anyway.

Editorial conclusion

springdoc-openapi-demos fits a Spring Boot team that wants a known-good OpenAPI 3 setup to read, run and copy, since every stack combination the project supports is a separate module you can start and inspect rather than a configuration described in prose. It does not fit a project looking for a starter template, because the modules are demonstration applications with their own domain models and controllers rather than a reusable dependency, and the repository itself publishes no releases to depend on. Before adopting it, open the module closest to your stack and check that its Spring Boot generation matches the one you run, read SUPPORT.md for how the project wants questions asked, and treat the missing documentation on the demo sources themselves as the gap you will have to fill from the springdoc.org site.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. springdoc/springdoc-openapi-demos on GitHub