springdoc-openapi generate openapi yaml on build without server

user_6392523 0
Viewed 5148

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?
springdoc openapi spring-boot spring
3 Answers

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.

user_11330210

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)
    
}
user_145903670

This happens because sometimes embedded server took sometime to start and it has 30 sec default setting. Please add the below properties in your openAPI block and it will work fine for you. Please see the below sample:

openApi {
apiDocsUrl.set("http://localhost:9090/v3/api-docs.yaml")
outputDir.set(file("Your Directory path"))
outputFileName.set("openapi.yaml")
forkProperties.set("-Dserver.port=9090")
waitTimeInSeconds.set(60)
}
user_168811080
Related