Скачать или смотреть Resolving the Missing Schemas Issue in Springdoc-OpenAPI with Security Schemes

Discover how to fix the issue of missing schemas in Springdoc-OpenAPI when adding security schemes programmatically in your Spring Boot application.
---
This video is based on the question https://stackoverflow.com/q/65331547/ asked by the user 'GloWorm' ( https://stackoverflow.com/u/14840052/ ) and on the answer https://stackoverflow.com/a/65364251/ provided by the user 'GloWorm' ( https://stackoverflow.com/u/14840052/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: Schemas disappear from components when programmatically adding security scheme

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
Introduction: The Dilemma of Missing Schemas

As developers, we often encounter challenges when transitioning between libraries and frameworks. One common scenario is moving from Springfox to Springdoc-openapi when generating OpenAPI documentation for a Spring Boot REST API service. While this migration typically allows for smoother API documentation generation, complications can arise—especially when introducing security configurations.

A user recently faced an issue where their schemas vanished from the Swagger UI after implementing a security scheme. The error message was quite confusing, stating:

[[See Video to Reveal this Text or Code Snippet]]

This guide will dissect the problem and offer a comprehensive solution to ensure your schemas remain visible even with security integration.

Understanding the Problem

Background Context

The user had set up security configurations and started experiencing missing schemas. Using Spring Boot version 2.4.0 along with Springdoc-openapi-ui version 1.5.1, they configured the OpenAPI documentation programmatically. However, after the addition of a security scheme, the schemas associated with their APIs in the Swagger UI were no longer generated.

Symptoms

Schemas not appearing in the Swagger UI for the v2 API group.

An error indicating that particular schemas (like Ping) cannot be found.

The user’s security configurations were mostly correct, yet it appears that including a custom OpenAPI setup inadvertently suppressed the standard scanned components, which included the schemas.

The Solution: Optimize Your OpenAPI Configuration

To resolve this mysterious disappearance of schemas, the configuration must be tweaked. Here’s how to do it effectively:

Step 1: Define a Custom OpenAPI Bean

Instead of solely relying on the OpenApiCustomiser, a custom OpenAPI bean should be created. This custom bean will explicitly include security schemes while ensuring that schemas are not overridden.

Here's the new configuration:

[[See Video to Reveal this Text or Code Snippet]]

Step 2: Configure API Groups

Continue to define your API groups (v1 and v2) as shown below. However, we remove the custom handling that was causing issues with schemas:

[[See Video to Reveal this Text or Code Snippet]]

Step 3: Simplify OpenApi Customisers

Further simplify your OpenApi customisers by merely adjusting the version information without compromising the schemas:

[[See Video to Reveal this Text or Code Snippet]]

Step 4: Maintain Schema Definitions

Your existing schema definitions should automatically be included without any additional configurations beyond the basic setups provided. Ensure your requests mapping annotations such as @ Operation and custom annotations like @ OkResponse remain intact.

Conclusion: A Unified Approach

With this adjusted configuration, your schemas will no longer be lost when applying security schemes to your OpenAPI documentation. The optimized approach not only resolves the immediate issue but also streamlines the maintenance of schema definitions across your API versions.

Changing how the OpenAPI is constructed allows for both security features and schema components to be visible. This will lead to a more robust and user-friendly API documentation experience.

Feel free to implement this updated configuration and see your schemas come back to life in the Swagger UI!