{"id":15091396,"url":"https://github.com/openapi-tools/swagger-maven-plugin","last_synced_at":"2025-05-12T14:52:33.320Z","repository":{"id":27219743,"uuid":"102495635","full_name":"openapi-tools/swagger-maven-plugin","owner":"openapi-tools","description":"Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.","archived":false,"fork":false,"pushed_at":"2024-07-27T11:30:21.000Z","size":131,"stargazers_count":73,"open_issues_count":59,"forks_count":48,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-09T20:04:10.808Z","etag":null,"topics":["api-documentation","api-documentation-tool","api-rest","easy-openapi-specification","openapi","openapi-component","openapi-maven-plugin","openapi-specification","openapi-tools","swagger-api","swagger-maven-plugin"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openapi-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-05T15:03:06.000Z","updated_at":"2024-11-21T01:10:30.000Z","dependencies_parsed_at":"2024-07-27T12:42:29.418Z","dependency_job_id":"65c74f95-6dc4-4dfa-aff4-551de639f85c","html_url":"https://github.com/openapi-tools/swagger-maven-plugin","commit_stats":{"total_commits":87,"total_committers":14,"mean_commits":6.214285714285714,"dds":0.632183908045977,"last_synced_commit":"524970448a09180b46e9085dc00418b177cf0833"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-maven-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-maven-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-maven-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openapi-tools%2Fswagger-maven-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openapi-tools","download_url":"https://codeload.github.com/openapi-tools/swagger-maven-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253759062,"owners_count":21959694,"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":["api-documentation","api-documentation-tool","api-rest","easy-openapi-specification","openapi","openapi-component","openapi-maven-plugin","openapi-specification","openapi-tools","swagger-api","swagger-maven-plugin"],"created_at":"2024-09-25T10:40:56.548Z","updated_at":"2025-05-12T14:52:33.299Z","avatar_url":"https://github.com/openapi-tools.png","language":"Java","readme":"# Swagger Maven Plugin\n\nThis plugin is intended to use the [Swagger Core library](https://github.com/swagger-api/swagger-core) to generate\nOpenAPI documentation from a JAX-RS based REST service with as little change as possible. This allows for @SwaggerDefinition, @ReaderListener and ModelConverters to work the same way as with the core Swagger library.\n\n\n# Status\n\nThe plugin is considered production ready. The version 2.x.x of the plugin is supporting generation of OpenAPI version 3 specifications using Swagger 2.x. To generate OpenAPI version 2 specifications using Swagger 1.x use the latest 1.x.x version of the plugin.\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.openapitools.swagger/swagger-maven-plugin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.openapitools.swagger/swagger-maven-plugin/)\n[![Javadoc](https://javadoc.io/badge/io.openapitools.swagger/swagger-maven-plugin/badge.svg)](https://www.javadoc.io/doc/io.openapitools.swagger/swagger-maven-plugin)\n[![Build status](https://travis-ci.org/openapi-tools/swagger-maven-plugin.svg?branch=master)](https://travis-ci.org/openapi-tools/swagger-maven-plugin)\n[![Known Vulnerabilities](https://snyk.io/test/github/openapi-tools/swagger-maven-plugin/badge.svg)](https://snyk.io/test/github/openapi-tools/swagger-maven-plugin) \n\n\n# Usage\n\nTo have Swagger generate the OpenAPI specifications as part of the build add in the plugin to the POM.\n\n```xml\n\u003cbuild\u003e\n  \u003cplugins\u003e\n    ...\n    \u003cplugin\u003e\n      \u003cgroupId\u003eio.openapitools.swagger\u003c/groupId\u003e\n      \u003cartifactId\u003eswagger-maven-plugin\u003c/artifactId\u003e\n      \u003cconfiguration\u003e\n        \u003cresourcePackages\u003e\n          \u003cresourcePackage\u003eio.openapitools.swagger.example\u003c/resourcePackage\u003e\n          \u003cresourcePackage\u003eio.openapitools.swagger.example.alternate\u003c/resourcePackage\u003e\n        \u003c/resourcePackages\u003e\n        \u003coutputDirectory\u003e${basedir}/target/\u003c/outputDirectory\u003e\n        \u003coutputFilename\u003eswagger\u003c/outputFilename\u003e\n        \u003coutputFormats\u003eJSON,YAML\u003c/outputFormats\u003e\n        \u003cprettyPrint\u003etrue\u003c/prettyPrint\u003e\n      \u003c/configuration\u003e\n      \u003cexecutions\u003e\n        \u003cexecution\u003e\n          \u003cgoals\u003e\n            \u003cgoal\u003egenerate\u003c/goal\u003e\n          \u003c/goals\u003e\n        \u003c/execution\u003e\n      \u003c/executions\u003e\n    \u003c/plugin\u003e\n    ...\n  \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\nThis will run the generation in the prepare-package lifecycle stage of the Maven build.\n\n## Specifying Packages with JAX-RS Endpoints\n\nThe packages containing JAX-RS endpoints must be configured using the resourcePackages element. See the minimal configuration above.\n\n## Properties of Swagger model\n\nMost general properties of the Swagger model is configurable using the swaggerConfig element. Note this may also be configured through the @OpenAPIDefinition annotation - see [Customizing your auto-generated Swagger Definitions](http://swagger.io/customizing-your-auto-generated-swagger-definitions-in-1-5-x/).\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eio.openapitools.swagger\u003c/groupId\u003e\n  \u003cartifactId\u003eswagger-maven-plugin\u003c/artifactId\u003e\n  \u003cconfiguration\u003e\n    \u003cswaggerConfig\u003e\n      \u003cservers\u003e\n        \u003cserver\u003e\n          \u003curl\u003ehttps://services.exmple.it/base/path\u003c/url\u003e\n          \u003cdescription\u003eEndpoint URL\u003c/description\u003e\n        \u003c/server\u003e\n      \u003c/servers\u003e\n      \u003cinfo\u003e\n        \u003ctitle\u003eTitle\u003c/title\u003e\n        \u003cversion\u003e1.0.0\u003c/version\u003e\n        \u003ctermsOfService\u003eTerms\u003c/termsOfService\u003e\n        \u003ccontact\u003e\n          \u003cemail\u003ee@mail.com\u003c/email\u003e\n          \u003cname\u003eMy Name\u003c/name\u003e\n          \u003curl\u003ehttps://google.com\u003c/url\u003e\n        \u003c/contact\u003e\n        \u003clicense\u003e\n          \u003curl\u003ehttps://license\u003c/url\u003e\n          \u003cname\u003eMIT\u003c/name\u003e\n        \u003c/license\u003e\n        \u003cextensions\u003e\n          \u003cx-custom-field-1\u003emy-custom-field-1\u003c/x-custom-field-1\u003e\n          \u003cx-custom-field-2\u003emy-custom-field-2\u003c/x-custom-field-2\u003e\n        \u003c/extensions\u003e\n      \u003c/info\u003e\n      \u003cdescriptionFile\u003esrc/test/resources/descriptions.md\u003c/descriptionFile\u003e\n    \u003c/swaggerConfig\u003e\n```\n\n\n## Deploying\n\nThe generated OpenAPI specifications may be installed and deployed as Maven artifact. To enable this add the configuration parameter attachSwaggerArtifact.\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eio.openapitools.swagger\u003c/groupId\u003e\n  \u003cartifactId\u003eswagger-maven-plugin\u003c/artifactId\u003e\n  \u003cconfiguration\u003e\n    \u003cattachSwaggerArtifact\u003etrue\u003c/attachSwaggerArtifact\u003e\n```\n\n# Acknowledgement\n\nThanks to [Yukai Kong](https://github.com/kongchen) for his work on\n[Swagger Maven plugin](https://github.com/kongchen/swagger-maven-plugin). This plugin is heavily inspired by that.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-tools%2Fswagger-maven-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenapi-tools%2Fswagger-maven-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenapi-tools%2Fswagger-maven-plugin/lists"}