springdoc-openapi generate openapi yaml on build without server

5
votes

I have a Spring boot Gradle project and I want to get it's OpenAPI spec YAML file.

As I understand the official swagger-core does not support Spring boot projects, thus I found springdoc-openapi (https://github.com/springdoc/springdoc-openapi-gradle-plugin).

It seems that in order to get the YAML/JSON files, when running the generateOpenApiDocs task, the springdoc library sets up a server with some endpoints (/v3/api-docs) to download the files.

  1. I'm using the default configuration, and for some reason I keep getting the following error:

Execution failed for task 'generateOpenApiDocs'. Unable to connect to http://localhost:8080/v3/api-docs waited for 30 seconds

It seems that for some reason it does not set up the server. How can I fix it?

  1. Is it possible to skip the server part? Can I configure springdoc to simply generate files on build?
2
springspring-bootopenapispringdoc

2 Answers

1
votes

If you are deploying REST APIs with spring-boot, you are relying on a servlet container.

The necessry metadata for the OpenAPI spec are only available by spring framework on runtime, which explains the choice of generation at runtime.

You can define any embeded servlet container, during your integration tests to generate the OpenAPI Spec.

0
votes

This is how I resolved the issue

  • Specify the path
  • In your properties file enter:
springdoc:
  api-docs:
    path: /{your path}
  • Configure the plugin
  • In your build.gradle file enter:
openApi {
    apiDocsUrl.set("http://localhost:{your port}/your path)
    
}