Spring Boot API documentation

Serve the OpenAPI document that springdoc-openapi generates from your controllers as an interactive API reference, with Scalar's official Spring Boot starter and two lines in application.properties.

Spring Boot teams usually get OpenAPI from springdoc-openapi, which inspects your @RestController classes and serves the document at /v3/api-docs. springdoc bundles Swagger UI as its default viewer. Scalar replaces that viewer, not the generator: you keep springdoc for the document and add com.scalar.maven:scalar-webmvc (or scalar-webflux) for the reference. Both Scalar modules are maintained by Scalar and published to Maven Central.

Set it up in three steps

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
  <!-- 2.x for Spring Boot 3; check springdoc.org for your Boot version -->
  <version>2.9.1</version>
</dependency>

<dependency>
  <groupId>com.scalar.maven</groupId>
  <artifactId>scalar-webmvc</artifactId>
  <version>0.6.74</version>
</dependency>

implementation 'com.scalar.maven:scalar-webmvc:0.6.74'

# application.properties
scalar.enabled=true
scalar.url=/v3/api-docs

See it live

The Scalar Galaxy demo runs the same renderer on an example API with authentication, schemas, and webhooks. Try search, the code samples, and the "Test Request" button.

What you get

Configuration in Spring's own style. Everything is a scalar.* property in application.properties or application.yml: scalar.theme, scalar.layout, scalar.showSidebar, scalar.hideModels, scalar.documentDownloadType, and more. Several OpenAPI documents (for example grouped APIs or v1 and v2) go under scalar.sources, with a document switcher in the UI:

scalar:
  enabled: true
  sources:
    - url: /v3/api-docs/v1
      title: API v1
      slug: v1
      isDefault: true
    - url: /v3/api-docs/v2
      title: API v2
      slug: v2

Spring Security and Actuator. The reference is served at a normal path, so a requestMatchers("/scalar/**").authenticated() rule protects it. Set scalar.actuatorEnabled=true and expose scalar to serve it at /actuator/scalar next to your other management endpoints. For per-request changes, extend ScalarWebMvcController and override configureProperties.

An API client with auth prefilled. Each operation has a "Test Request" button that opens the Scalar API client. For local testing, scalar.authentication.* properties can prefill API keys, bearer tokens, or OAuth2 flows for the security schemes springdoc emits. Do not use prefilled secrets in production, because they are visible in the browser.

SDKs. The Scalar SDK generator reads the document at /v3/api-docs. TypeScript, Python, Go, and CLI targets are generally available. Java and Kotlin targets exist but are experimental, as are Ruby, C#, PHP, Rust, Swift, Dart, and C++. Every plan includes one SDK.

A hosted MCP server. Scalar can host an MCP server generated from the same OpenAPI document, with OAuth, so AI agents can call the endpoints you expose. Scalar runs it; there is nothing extra to deploy next to your Spring service. Hosted MCP servers are included from the Pro plan.

The Java integration and the renderer are MIT licensed. Hosted docs, SDKs, and MCP servers are on the pricing page.

Common gotchas

The page loads but shows no operations. The browser fetches the document from scalar.url, so that path has to be reachable by the same user. If Spring Security protects everything, permit /v3/api-docs/** alongside /scalar/**, or the reference will get a login redirect instead of JSON.

The app runs under a context path. With server.servlet.context-path=/api, the document lives at /api/v3/api-docs. Set scalar.url to the full path.

Requests from "Test Request" go to the wrong host. springdoc infers the servers entry from the incoming request, which can be wrong behind a proxy. Use scalar.servers to list the real base URLs, or fix the forwarded headers so springdoc sees the public host.

You split the API into groups. springdoc serves each GroupedOpenApi bean at /v3/api-docs/{group}. List each one under scalar.sources, as in the YAML example above, rather than pointing scalar.url at a single group.

Migrating from Swagger UI or Redoc

springdoc's springdoc-openapi-starter-webmvc-ui artifact is the API starter plus Swagger UI. Switching is a dependency swap:

1. Replace springdoc-openapi-starter-webmvc-ui with springdoc-openapi-starter-webmvc-api. Your @Operation, @Schema, and @Tag annotations and your springdoc.* properties are unaffected.
2. Add scalar-webmvc and set scalar.url=/v3/api-docs.
3. If people bookmarked the old Swagger UI page, keep the -ui starter for a release and turn it off later with springdoc.swagger-ui.enabled=false, or set scalar.path to a path your team already knows.

If you customized the document path with springdoc.api-docs.path, use the same value for scalar.url. Redoc setups migrate the same way, since Redoc also reads the springdoc document. The Swagger UI migration guide covers the general steps.

Frequently asked questions

Get started

implementation 'com.scalar.maven:scalar-webmvc:0.6.74'

Or create a free Scalar account to host the reference on its own domain.

Related

• Learn: What is an API reference? · OpenAPI security schemes
• Docs: Java and Spring Boot integration reference
• Product: Scalar API References — the open-source renderer behind the Spring Boot starter