{"id":23065566,"url":"https://github.com/berkleytechnologyservices/restdocs-spec","last_synced_at":"2025-04-07T11:10:57.412Z","repository":{"id":37025375,"uuid":"145861384","full_name":"BerkleyTechnologyServices/restdocs-spec","owner":"BerkleyTechnologyServices","description":"A maven plugin for generating Open API and Postman Collection specifications using Spring Restdocs.","archived":false,"fork":false,"pushed_at":"2024-10-29T00:13:12.000Z","size":391,"stargazers_count":56,"open_issues_count":11,"forks_count":18,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-29T15:11:13.470Z","etag":null,"topics":["api-documentation","maven","maven-plugin","openapi","spring-rest-docs","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","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/BerkleyTechnologyServices.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2018-08-23T13:59:20.000Z","updated_at":"2024-10-25T21:59:34.000Z","dependencies_parsed_at":"2023-02-13T21:30:56.631Z","dependency_job_id":"fef0107a-50a2-4d46-b755-a649be372efe","html_url":"https://github.com/BerkleyTechnologyServices/restdocs-spec","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BerkleyTechnologyServices%2Frestdocs-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BerkleyTechnologyServices%2Frestdocs-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BerkleyTechnologyServices%2Frestdocs-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BerkleyTechnologyServices%2Frestdocs-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BerkleyTechnologyServices","download_url":"https://codeload.github.com/BerkleyTechnologyServices/restdocs-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"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","maven","maven-plugin","openapi","spring-rest-docs","swagger"],"created_at":"2024-12-16T05:09:00.028Z","updated_at":"2025-04-07T11:10:57.391Z","avatar_url":"https://github.com/BerkleyTechnologyServices.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Restdocs Spec Generation Support\n\n[![Build Status](https://github.com/BerkleyTechnologyServices/restdocs-spec/workflows/CI/badge.svg?branch=master\u0026event=push)](https://github.com/BerkleyTechnologyServices/restdocs-spec/actions?query=branch%3Amaster+workflow%3ACI)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.berkleytechnologyservices/restdocs-spec)](https://central.sonatype.com/search?q=a%253Arestdocs-spec%2520g%253Aio.github.berkleytechnologyservices\u0026namespace=io.github.berkleytechnologyservices)\n\n## Usage\n\nFirst head over to the [ePages-de/restdocs-api-spec](https://github.com/ePages-de/restdocs-api-spec) project\nand follow the instructions for setting up the Spring REST Docs extension.  That extension will produce\n`resource.json` files for each of your documented resources.  You'll also notice that project provides\na gradle plugin that can be used to read all the `resource.json` files and turn them into an OpenAPI spec\nfile.  That is exactly what this project does as well, only in the form of a maven plugin instead.\n\nHere is a typical `pom.xml` configuration:\n\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\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\nThat will read your `resource.json` snippet files found under the `${project.build.directory}/generated-snippets`\ndirectory and produce an OpenAPI 2.0 YAML file at `${project.build.directory}/restdocs-spec/openapi-2.0.yml`.\n\nIf you would prefer that the OpenAPI 2.0 document is in JSON format you can specify it like this:\n\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003cformat\u003eJSON\u003c/format\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\nYou can also generate OpenAPI 3.0 or Postman Collection specification. For instance, this would generate OpenAPI 3.0:\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003cspecification\u003eOPENAPI_V3\u003c/specification\u003e\u003c!-- switch this to POSTMAN_COLLECTION for Postman Collection specs --\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\nFinally, you can also generate multiple formats at once using the more verbose syntax:\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003cspecifications\u003e\n            \u003cspecification\u003e\n              \u003ctype\u003eOPENAPI_V2\u003c/type\u003e\n            \u003c/specification\u003e\n            \u003cspecification\u003e\n              \u003ctype\u003eOPENAPI_V3\u003c/type\u003e\n              \u003cformat\u003eJSON\u003c/format\u003e\n            \u003c/specification\u003e\n            \u003cspecification\u003e\n              \u003ctype\u003ePOSTMAN_COLLECTION\u003c/type\u003e\n              \u003cfilename\u003emy-api-collection\u003c/filename\u003e\n            \u003c/specification\u003e\n          \u003c/specifications\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\n\nThere are several other aspects you can optionally configure.  Here is the full set of options with their default values:\n\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003cname\u003e${project.artifactId}\u003c/name\u003e\n          \u003cversion\u003e${project.version}\u003c/version\u003e\n          \u003chost\u003elocalhost\u003c/host\u003e\n          \u003cbasePath\u003e\u003c/basePath\u003e\n          \u003cschemes\u003e\n            \u003cscheme\u003ehttp\u003c/scheme\u003e\n          \u003c/schemes\u003e\n          \u003csnippetsDirectory\u003e${project.build.directory}/generated-snippets\u003c/snippetsDirectory\u003e\n          \u003cspecification\u003eOPENAPI_V2\u003c/specification\u003e\n          \u003coutputDirectory\u003e${project.build.directory}/restdocs-spec\u003c/outputDirectory\u003e\n          \u003cskip\u003efalse\u003c/skip\u003e\n          \u003cformat\u003eYAML\u003c/format\u003e\n          \u003cfilename\u003eopenapi-2.0\u003c/filename\u003e\n          \u003cseparatePublicApi\u003efalse\u003c/separatePublicApi\u003e\n          \u003ctags /\u003e\n          \u003coauth2 /\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\n### Tags\n\nBy default the plugin will not generate any tags.  You can optionally provide tags using the\n `\u003ctags /\u003e` element.  Here is an example:\n\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003ctags\u003e\n            \u003ctag\u003e\n              \u003cname\u003epets\u003c/name\u003e\n              \u003cdescription\u003eEverything about your Pets\u003c/description\u003e\n            \u003c/tag\u003e\n            \u003ctag\u003e\n              \u003cname\u003estore\u003c/name\u003e\n              \u003cdescription\u003eAccess to Petstore orders\u003c/description\u003e\n            \u003c/tag\u003e\n          \u003c/tags\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\n### OAuth2 Configuration\n\nBy default the plugin will not generate any security information.  You can optionally provide\nit using the `\u003coauth2 /\u003e` element.  Here is an example:\n\n```xml\n  \u003cplugin\u003e\n    \u003cgroupId\u003eio.github.berkleytechnologyservices\u003c/groupId\u003e\n    \u003cartifactId\u003erestdocs-spec-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${restdocs-spec.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n      \u003cexecution\u003e\n        \u003cgoals\u003e\n          \u003cgoal\u003egenerate\u003c/goal\u003e\n        \u003c/goals\u003e\n        \u003cconfiguration\u003e\n          \u003coauth2\u003e\n            \u003ctokenUrl\u003ehttp://example.com/uaa/token\u003c/tokenUrl\u003e\n            \u003cauthorizationUrl\u003ehttp://example.com/uaa/authorize\u003c/authorizationUrl\u003e\n            \u003cflows\u003e\n              \u003cflow\u003eaccessCode\u003c/flow\u003e\n              \u003cflow\u003eimplicit\u003c/flow\u003e\n            \u003c/flows\u003e\n            \u003cscopes\u003e\n              \u003cscope\u003e\n                \u003cname\u003eread\u003c/name\u003e\n                \u003cdescription\u003eAccess to read operations.\u003c/description\u003e\n              \u003c/scope\u003e\n              \u003cscope\u003e\n                \u003cname\u003ewrite\u003c/name\u003e\n                \u003cdescription\u003eAccess to write operations.\u003c/description\u003e\n              \u003c/scope\u003e\n            \u003c/scopes\u003e\n          \u003c/oauth2\u003e\n        \u003c/configuration\u003e\n      \u003c/execution\u003e\n    \u003c/executions\u003e\n  \u003c/plugin\u003e\n```\n\n## Example\n\nYou can find a full example project here: https://github.com/BerkleyTechnologyServices/restdocs-spec-example\n\n## Still in development\n\n* Support for additional specification formats is currently in development.  We plan to add\n  support for Postman Collections and RAML.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkleytechnologyservices%2Frestdocs-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberkleytechnologyservices%2Frestdocs-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkleytechnologyservices%2Frestdocs-spec/lists"}