This is available from the FAQ page in the spring-doc documentation. See What is a proper way to set up Swagger UI to use provided spec.yml? and How can use custom json/yml file instead of generated one ? of the same page.

Example from the FAQ page

  1. Turn off auto-generation in the project property file springdoc.api-docs.enabled=false
  2. Put your yaml file in src/main/resources/static such as src/main/resources/static/myApiFile.yaml
  3. Set the swagger-ui url for the file springdoc.swagger-ui.url=/myApiFile.yaml
  4. Enable the minimal beans configuration
import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocsConfiguration {

  @Bean
  SpringDocConfiguration springDocConfiguration() {
    return new SpringDocConfiguration();
  }

  @Bean
  public SpringDocConfigProperties springDocConfigProperties() {
    return new SpringDocConfigProperties();
  }
}
Answer from antonkronaj on Stack Overflow
🌐
Stripe
docs.stripe.com › api
Stripe API Reference
January 29, 2026 - A sample test API key is included in all the examples here, so you can test any example right away.
🌐
GitHub
github.com › thim81 › openapi-format
GitHub - thim81/openapi-format: Format an OpenAPI document by ordering, formatting and filtering fields. · GitHub
Template Options: In the customGenerate.yaml, you can define templates for various OpenAPI properties using dynamic placeholders. These placeholders will be replaced by actual values from the OpenAPI operations. Below is a list of available placeholders and what they represent: <operationId> : The operationId of the OpenAPI operation. Example: leadsAll
Starred by 160 users
Forked by 25 users
Languages   JavaScript
🌐
Swagger
swagger.io › docs › specification › v2_0 › adding-examples
Adding Examples | Swagger Docs
See also this post on Stack Overflow for tips on how to write multi-line strings in YAML. If there are multiple examples on different levels (property, schema, response), the higher-level example is used by the tool that is processing the spec. That is, the order of precedence is: ... OpenAPI 2.0 example and examples keywords require inline examples and do not support $ref.
🌐
Medium
medium.com › swlh › restful-apis-tutorial-of-openapi-specification-eeada0e3901d
RESTful APIs: Tutorial of OpenAPI Specification | by Amir Lavasani | Medium
September 22, 2019 - In this tutorial, we will be building a blog posts API using OpenAPI Specification and we create documentation for our API. We also shortly go over the ways to generate code for client and server. The examples in this article are in YAML but you can write your OAS also in JSON.
🌐
Phil Sturgeon
philsturgeon.com › openapi-examples
OpenAPI Examples Need Help
December 27, 2023 - There is more than just an s difference between these keywords, they're different shapes too. example is singular example which just contains the actual example value. # OpenAPI v3 responses: "200": description: OK content: application/json: example: id: 1 name: get food completed: false schema: properties: id: type: integer name: type: string completed: type: boolean completed_at: type: string format: date-time nullable: true required: - id - name - completed
🌐
ApisYouWontHate
apisyouwonthate.com › blog › learn-openapi-from-these-realistic-examples
Learn OpenAPI from these Realistic Examples
December 2, 2024 - - GitHub - Redocly/museum-openapi-example: An example OpenAPI description for an imaginary Museum API.
Top answer
1 of 5
22

This is available from the FAQ page in the spring-doc documentation. See What is a proper way to set up Swagger UI to use provided spec.yml? and How can use custom json/yml file instead of generated one ? of the same page.

Example from the FAQ page

  1. Turn off auto-generation in the project property file springdoc.api-docs.enabled=false
  2. Put your yaml file in src/main/resources/static such as src/main/resources/static/myApiFile.yaml
  3. Set the swagger-ui url for the file springdoc.swagger-ui.url=/myApiFile.yaml
  4. Enable the minimal beans configuration
import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocsConfiguration {

  @Bean
  SpringDocConfiguration springDocConfiguration() {
    return new SpringDocConfiguration();
  }

  @Bean
  public SpringDocConfigProperties springDocConfigProperties() {
    return new SpringDocConfigProperties();
  }
}
2 of 5
6

This answer is excellent and lead me to the right direction. I applied all steps but the code section had a difference with the link provided. In the link provided the code suggested contains also an ObjectMapperProvider which is absent in that answer.

Also once the changes are applied the endpoint to verify the modification that worked for me was http://localhost:8080/swagger-ui/index.html

Hope this helps clarify, but all the information is already there. Thanks.

import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springdoc.core.providers.ObjectMapperProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Provides the capabilities to display the apiDoc in a preconfigured endpoint based on the following information of open-api
 * https://springdoc.org/faq.html#_what_is_a_proper_way_to_set_up_swagger_ui_to_use_provided_spec_yml
 * This apiDoc can be consulted through the endpoint: http://localhost:8080/swagger-ui/index.html
 */
@Configuration
public class SpringDocsConfiguration {

    @Bean
    SpringDocConfiguration springDocConfiguration() {
        return new SpringDocConfiguration();
    }

    @Bean
    public SpringDocConfigProperties springDocConfigProperties() {
        return new SpringDocConfigProperties();
    }

    @Bean
    ObjectMapperProvider objectMapperProvider(SpringDocConfigProperties springDocConfigProperties){
        return new ObjectMapperProvider(springDocConfigProperties);
    }
}
Find elsewhere
🌐
Swagger
swagger.io › docs › specification › v3_0 › basic-structure
Basic Structure | Swagger Docs
A sample OpenAPI 3.0 definition written in YAML looks like: ... description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML. ... All keyword names are case-sensitive. Every API definition must include the version of the OpenAPI Specification ...
🌐
GitHub
github.com › OAI › OpenAPI-Specification
GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository · GitHub
This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project.
Starred by 30.9K users
Forked by 9.2K users
Languages   Markdown 95.8% | HTML 1.5% | JavaScript 1.4%
🌐
GitHub
github.com › Redocly › openapi-starter › blob › main › openapi › openapi.yaml
openapi-starter/openapi/openapi.yaml at main · Redocly/openapi-starter
altText: OpenAPI example logo · description: > This is an **example** API to demonstrate features of the OpenAPI · specification. · # Introduction · · This API definition is intended to to be a good starting point for · describing your API in [OpenAPI/Swagger ·
Author   Redocly
🌐
Apify
docs.apify.com › api › v2
Apify API | Apify Documentation
You can download the complete OpenAPI schema of Apify API in the YAML or JSON formats.
🌐
OpenAPI
learn.openapis.org › examples › v3.0 › api-with-examples.html
api-with-examples
{ "openapi": "3.0.0", "info": { "title": "Simple API overview", "version": "2.0.0" }, "paths": { "/": { "get": { "operationId": "listVersionsv2", "summary": "List API versions", "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "foo": { "value": { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self"
🌐
DZone
dzone.com › software design and architecture › integration › a sample openapi 3.0 file to get started
A Sample OpenAPI 3.0 File to Get Started
September 18, 2017 - Familiarize yourself with the new OpenAPI specification version 3.0 by looking over this example file, with an analysis and thoughts from the API Evangelist.
🌐
Nordic APIs
nordicapis.com › 3-example-openapi-definitions
3 Example OpenAPI Definitions | Nordic APIs |
May 24, 2024 - The Train Travel API is also contained in a single openapi.yaml file, making it slightly more efficient for use in mockups and documentation. The Train Travel API is based on real-world examples, making it slightly more useful and practical than the PetStore API.
🌐
Stoplight
stoplight.io › openapi
OpenAPI | OpenAPI Definition & Online Tools | Open API Standards List | Stoplight
It can be helpful to review some OpenAPI examples to see how the documents actually look. The following are small OpenAPI 3.0 examples to show different request types. This is a complete, but simple, API example with a single endpoint and operation, written as YAML:
🌐
Redocly
redocly.com › learn › openapi › learning-openapi
Introduction to OpenAPI
You can use `markdown` here. ... application/json: schema: $ref: ../components/schemas/User.yaml example: username: user1 email: user@example.com '403': description: Forbidden '404': description: User not found put: tags: ...
🌐
Medium
medium.com › @joshuaondieki › rest-api-docs-with-openapi-swagger-ui-de9cd7944c6
REST API docs with OpenAPI & Swagger UI | by Joshua Ondieki | Medium
May 21, 2023 - An example is available at GitHub: express-api-with-openapi-docs · We’ll write our API docs in YAML format using OpenAPI OpenAPI Specification docs are available here
🌐
Swagger
swagger.io › specification
OpenAPI Specification - Version 3.1.0 | Swagger
The OpenAPI Specification defines a standard interface to RESTful APIs which allows both humans and computers to understand service capabilities without access to source code, documentation, or network traffic inspection.
🌐
Stack Overflow
stackoverflow.com › questions › 72627474 › how-to-add-openapi-yaml-to-your-project
java - How to add openapi.yaml to your project - Stack Overflow
42 How to generate OpenAPI 3.0 YAML file from existing Spring REST API? 10 How to generate JSON examples from OpenAPI 3.0 yaml file? 8 OpenApi Generator reference an external POJO in YAML file specification · 0 Failing to add examples to YAML file · 11 Using openapi.yaml in springdoc ·