CODEWITHSUNDEEP
springspring-bootopenapispringdoc
ChikChak
ChikChak

Reputation: 1034

springdoc-openapi generate openapi yaml on build without server

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?

Upvotes: 17

Views: 16927

Answers (4)

Jack
Jack

Reputation: 658

You need to add the dependency below, an updated version may exist depending on when you're seeing this - intellij would tell you and help upgrade:

implementation('org.springdoc:springdoc-openapi-ui:1.6.11')

Then add the line below to your application.properties file:

springdoc.api-docs.path=/api-docs

Perhaps also get rid of the plugin, it's not necessary as long as you have the above dependency. I got rid of mine and things work fine.

After the dependency is resolved, run the app normally with intellij run buttons or the commandline.

With the app running, visit http://localhost:8080/swagger-ui/index.html - assuming your app is running on port 8080. If not, use the right port accordingly.

Also, you can check out https://github.com/springdoc/springdoc-openapi-gradle-plugin/issues/10 and https://github.com/springdoc/springdoc-openapi-gradle-plugin/issues/10#issuecomment-594010078 - those were helpful when I faced the same issue, showed me part of what to do.

Upvotes: 3

user16881108
user16881108

Reputation: 11

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

Upvotes: 1

Izu
Izu

Reputation: 21

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

Upvotes: 2

brianbro
brianbro

Reputation: 4779

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.

Upvotes: 3

Related Questions