{"id":24975554,"url":"https://github.com/springdoc/springdoc-openapi-gradle-plugin","last_synced_at":"2025-04-13T04:10:50.584Z","repository":{"id":38003939,"uuid":"236890806","full_name":"springdoc/springdoc-openapi-gradle-plugin","owner":"springdoc","description":"Library for OpenAPI 3 with spring-boot","archived":false,"fork":false,"pushed_at":"2024-06-23T20:43:43.000Z","size":409,"stargazers_count":152,"open_issues_count":16,"forks_count":49,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-10T09:34:21.448Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://springdoc.org","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/springdoc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.adoc","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.adoc","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"open_collective":"springdoc-openapi"}},"created_at":"2020-01-29T02:50:57.000Z","updated_at":"2025-04-07T09:46:15.000Z","dependencies_parsed_at":"2024-01-09T05:03:44.826Z","dependency_job_id":"f2922bae-4280-4abb-b3f0-5b10b97f7f7f","html_url":"https://github.com/springdoc/springdoc-openapi-gradle-plugin","commit_stats":{"total_commits":136,"total_committers":28,"mean_commits":4.857142857142857,"dds":0.5882352941176471,"last_synced_commit":"e855f9c3aeb776f3d3ef285c80aca748c5a50950"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/springdoc","download_url":"https://codeload.github.com/springdoc/springdoc-openapi-gradle-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661704,"owners_count":21141450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-03T21:00:43.518Z","updated_at":"2025-04-13T04:10:50.559Z","avatar_url":"https://github.com/springdoc.png","language":"Kotlin","readme":"[![Build Status](https://ci-cd.springdoc.org:8443/buildStatus/icon?job=springdoc-openapi-gradle-IC)](https://ci-cd.springdoc.org:8443/view/springdoc-openapi/job/springdoc-openapi-gradle-IC/)\n\n# Introducing springdoc-openapi-gradle-plugin\n\nGradle plugin for springdoc-openapi.\n\nThis plugin allows you to generate an OpenAPI 3 specification for a Spring Boot\napplication from a Gradle build.\nCompatibility Notes\n-------------------\n\nThe plugin is built on Gradle version 7.0.\n\nDependencies\n------------\nThis plugin has a runtime dependency on the following plugins:\n\n1. Spring Boot Gradle plugin - `org.springframework.boot`\n2. Gradle process plugin - `com.github.psxpaul.execfork`\n\nHow To Use\n----------\n\nGradle Groovy DSL\n\n```groovy\nplugins {\n    id \"org.springframework.boot\" version \"2.7.0\"\n    id \"org.springdoc.openapi-gradle-plugin\" version \"1.9.0\"\n}\n```\n\nGradle Kotlin DSL\n\n```groovy\nplugins {\n    id(\"org.springframework.boot\") version \"2.7.0\"\n    id(\"org.springdoc.openapi-gradle-plugin\") version \"1.9.0\"\n}\n```\n\nNote: For latest versions of the plugins please check\nthe [Gradle Plugins portal](https://plugins.gradle.org/).\n\nHow the plugin works?\n------------\n\nWhen you add this plugin and its runtime dependency plugins to your build file, the plugin\ncreates the following tasks:\n\n1. forkedSpringBootRun\n\n2. generateOpenApiDocs\n\nRunning the task `generateOpenApiDocs` writes the OpenAPI spec into a `openapi.json` file\nin your project's build dir.\n\n```bash\ngradle generateOpenApiDocs\n``` \n\nWhen you run the gradle task **generateOpenApiDocs**, it starts your spring boot\napplication in the background using **forkedSpringBootRun** task.\nOnce your application is up and running **generateOpenApiDocs** makes a rest call to your\napplications doc url to download and store the open api docs file as json.\n\n\nCustomization\n-------------\n\nThe following customizations can be done on task generateOpenApiDocs using extension\nopenApi as follows\n\n```kotlin\nopenApi {\n\tapiDocsUrl.set(\"https://localhost:9000/api/docs\")\n\toutputDir.set(file(\"$buildDir/docs\"))\n\toutputFileName.set(\"swagger.json\")\n\twaitTimeInSeconds.set(10)\n\ttrustStore.set(\"keystore/truststore.p12\")\n\ttrustStorePassword.set(\"changeit\".toCharArray())\n\tgroupedApiMappings.set(\n\t\t[\"https://localhost:8080/v3/api-docs/groupA\" to \"swagger-groupA.json\",\n\t\t\t\"https://localhost:8080/v3/api-docs/groupB\" to \"swagger-groupB.json\"]\n\t)\n\tcustomBootRun {\n\t\targs.set([\"--spring.profiles.active=special\"])\n\t}\n\trequestHeaders = [\n\t\t\"x-forwarded-host\": \"custom-host\",\n\t\"x-forwarded-port\": \"7000\"\n\t]\n}\n```\n\n| Parameter            | Description                                                                                                                         | Required | Default                              |\n|----------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------|\n| `apiDocsUrl`         | The URL from where the OpenAPI doc can be downloaded. If the url ends with `.yaml`, output will YAML format.                                                                                 | No       | http://localhost:8080/v3/api-docs    |\n| `outputDir`          | The output directory for the generated OpenAPI file                                                                                 | No       | $buildDir - Your project's build dir |\n| `outputFileName`     | Specifies the output file name.                            | No       | openapi.json                         |\n| `waitTimeInSeconds`  | Time to wait in seconds for your Spring Boot application to start, before we make calls to `apiDocsUrl` to download the OpenAPI doc | No       | 30 seconds                           |\n| `trustStore`         | Path to a trust store that contains custom trusted certificates.                                                                    | No       | `\u003cNone\u003e`                             |\n| `trustStorePassword` | Password to open Trust Store                                                                                                        | No       | `\u003cNone\u003e`                             |\n| `groupedApiMappings` | A map of URLs (from where the OpenAPI docs can be downloaded) to output file names                                                  | No       | []                                   |\n| `customBootRun`      | Any bootRun property that you would normal need to start your spring boot application.                                              | No       | (N/A)                                |\n| `requestHeaders`     | customize Generated server url, relies on `server.forward-headers-strategy=framework`                                      | No       | (N/A)                                |\n\n### `customBootRun` properties examples\n\n`customBootRun` allows you to send in the properties that might be necessary to allow for\nthe forked spring boot application that gets started\nto be able to start (profiles, other custom properties, etc.)\n`customBootRun` allows you can specify bootRun style parameter, such\nas `args`, `jvmArgs`, `systemProperties` and `workingDir`.\nIf you don't specify `customBootRun` parameter, this plugin uses the parameter specified\nto `bootRun` in Spring Boot Gradle Plugin.\n\n#### Passing static args\n\nThis allows for you to be able to just send the static properties when executing Spring\napplication in `generateOpenApiDocs`.\n\n```\nopenApi {\n    customBootRun {\n        args = [\"--spring.profiles.active=special\"] \n    }\n}\n```\n\n#### Passing straight from gradle\n\nThis allows for you to be able to just send in whatever you need when you generate docs.\n\n`./gradlew generateOpenApiDocs -Dspring.profiles.active=special`\n\nand as long as the config looks as follows that value will be passed into the forked\nspring boot application.\n\n```\nopenApi {\n    customBootRun {\n         systemProperties = System.properties\n    }\n}\n```\n\n### Trust Store Configuration\n\nIf you have restricted your application to HTTPS only and prefer not to include your certificate\nin Java's cacerts file, you can configure your own set of trusted certificates through plugin\nproperties, ensuring SSL connections are established.\n\n#### Generating a Trust Store\n\nTo create your own Trust Store, utilize the Java keytool command:\n\n```shell\nkeytool -storepass changeit -noprompt -import -alias ca -file [CERT_PATH]/ca.crt -keystore [KEYSTORE_PATH]/truststore.p12 -deststoretype PKCS12\n```\n\n### Grouped API Mappings Notes\n\nThe `groupedApiMappings` customization allows you to specify multiple URLs/file names for\nuse within this plugin. This configures the plugin to ignore the `apiDocsUrl`\nand `outputFileName` parameters and only use those found in `groupedApiMappings`. The\nplugin will then attempt to download each OpenAPI doc in turn as it would for a single\nOpenAPI doc.\n\n# Building the plugin\n\n1. Clone the repo `git@github.com:springdoc/springdoc-openapi-gradle-plugin.git`\n2. Build and publish the plugin into your local maven repository by running the following\n    ```\n    ./gradlew clean pTML\n   ```\n\n# Testing the plugin\n\n1. Create a new spring boot application or use an existing spring boot app and follow\n   the `How To Use` section above to configure this plugin.\n2. Update the version for the plugin to match the current version found\n   in `build.gradle.kts`\n\n    ```\n    id(\"org.springdoc.openapi-gradle-plugin\") version \"1.8.0\"\n    ```\n\n3. Add the following to the spring boot apps `settings.gradle`\n\n    ```\n    pluginManagement {\n        repositories {\n            mavenLocal()\n            gradlePluginPortal()\n        }\n    }\n    ```\n\n# **Thank you for the support**\n\n* Thanks a lot [JetBrains](https://www.jetbrains.com/?from=springdoc-openapi) for\n  supporting springdoc-openapi project.\n\n![JetBrains logo](https://springdoc.org/img/jetbrains.svg)\n","funding_links":["https://opencollective.com/springdoc-openapi"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringdoc%2Fspringdoc-openapi-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspringdoc%2Fspringdoc-openapi-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringdoc%2Fspringdoc-openapi-gradle-plugin/lists"}