{"id":22213973,"url":"https://github.com/xmlking/rest-api-docs","last_synced_at":"2025-07-27T12:31:51.533Z","repository":{"id":142313662,"uuid":"49402739","full_name":"xmlking/rest-api-docs","owner":"xmlking","description":"Grails REST API with swagger style API docs","archived":false,"fork":false,"pushed_at":"2016-01-25T00:37:45.000Z","size":200,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-01T20:22:20.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xmlking.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-11T04:48:31.000Z","updated_at":"2016-03-21T15:07:06.000Z","dependencies_parsed_at":"2023-04-26T06:19:12.093Z","dependency_job_id":null,"html_url":"https://github.com/xmlking/rest-api-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmlking%2Frest-api-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmlking%2Frest-api-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmlking%2Frest-api-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xmlking%2Frest-api-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xmlking","download_url":"https://codeload.github.com/xmlking/rest-api-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227802821,"owners_count":17822113,"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":"2024-12-02T21:12:50.730Z","updated_at":"2024-12-02T21:12:51.371Z","avatar_url":"https://github.com/xmlking.png","language":"Groovy","readme":"rest-api-docs\r\n-------------\r\nAPI docs for Grails 3.1.x Restful API\r\n\r\nChallenge with REST API documentation is, it quickly get out of sync with current implementation as developers changes code.\r\n\r\nThis project demonstrate how developers can generate API docs and keep in sync with code changes using rahulsom's [swaggydoc](https://github.com/rahulsom/swaggydoc) plugin.\r\n\r\n![API Docs](./api-doc.png)\r\n\r\n### Setup\r\n\r\n1. Create a project\r\n\r\n    ```bash\r\n    # create a new API project\r\n    grails create-app rest-api-docs  \r\n    # grails create-app rest-api-docs --profile rest-api\r\n    # when using with `rest-api` profile, add `org.grails:grails-dependencies` to build.gradle\r\n    cd rest-api-docs\r\n    # create a domain and a controller\r\n    grails create-domain-class User\r\n    grails create-restful-controller User\r\n    # add URL mapping for this API in UrlMappings.groovy\r\n    \"/users\"(resources: 'user')\r\n    ```\r\n\r\n2. Add swaggydoc dependency after `profile` dependency\r\n\r\n    `compile \"org.grails.plugins:swaggydoc-grails3:0.26.0\"`\r\n\r\n3. Optionally annotate your REST controllers\r\n\r\n    1. Simple \r\n    \r\n        ```groovy\r\n        @Api(value = 'user', description = 'User Management  API')\r\n             class UserController extends RestfulController {\r\n                 static responseFormats = ['json', 'xml']\r\n                 UserController() {\r\n                     super(User)\r\n                 }\r\n             }\r\n        ```\r\n\r\n    2. Custom\r\n    \r\n        ```groovy\r\n        @Api(value = 'user', description = 'User Management  API')\r\n        class UserController extends RestfulController {\r\n            static responseFormats = ['json', 'xml']\r\n            UserController() {\r\n                super(User)\r\n            }\r\n            @SwaggyList\r\n            def index(Integer max) {\r\n                super.index(max)\r\n            }\r\n            @SwaggyShow\r\n            def show() {\r\n                super.show()\r\n            }\r\n            @Transactional\r\n            @SwaggySave\r\n            def save() {\r\n                super.save()\r\n            }\r\n            @Transactional\r\n            @SwaggyUpdate\r\n            def update() {\r\n                super.update()\r\n            }\r\n            @Transactional\r\n            @SwaggyDelete\r\n            def delete() {\r\n                super.delete()\r\n            }   \r\n        }\r\n        ``` \r\n\r\n4. Run app\r\n\r\n    ```bash\r\n    gradle bootRun\r\n    ```\r\n    \r\n    open  http://localhost:8080/api","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmlking%2Frest-api-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxmlking%2Frest-api-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxmlking%2Frest-api-docs/lists"}