https://github.com/xmlking/rest-api-docs
Grails REST API with swagger style API docs
https://github.com/xmlking/rest-api-docs
Last synced: 6 months ago
JSON representation
Grails REST API with swagger style API docs
- Host: GitHub
- URL: https://github.com/xmlking/rest-api-docs
- Owner: xmlking
- Created: 2016-01-11T04:48:31.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2016-01-25T00:37:45.000Z (almost 10 years ago)
- Last Synced: 2024-05-01T20:22:20.739Z (over 1 year ago)
- Language: Groovy
- Size: 195 KB
- Stars: 4
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
rest-api-docs
-------------
API docs for Grails 3.1.x Restful API
Challenge with REST API documentation is, it quickly get out of sync with current implementation as developers changes code.
This 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.
### Setup
1. Create a project
```bash
# create a new API project
grails create-app rest-api-docs
# grails create-app rest-api-docs --profile rest-api
# when using with `rest-api` profile, add `org.grails:grails-dependencies` to build.gradle
cd rest-api-docs
# create a domain and a controller
grails create-domain-class User
grails create-restful-controller User
# add URL mapping for this API in UrlMappings.groovy
"/users"(resources: 'user')
```
2. Add swaggydoc dependency after `profile` dependency
`compile "org.grails.plugins:swaggydoc-grails3:0.26.0"`
3. Optionally annotate your REST controllers
1. Simple
```groovy
@Api(value = 'user', description = 'User Management API')
class UserController extends RestfulController {
static responseFormats = ['json', 'xml']
UserController() {
super(User)
}
}
```
2. Custom
```groovy
@Api(value = 'user', description = 'User Management API')
class UserController extends RestfulController {
static responseFormats = ['json', 'xml']
UserController() {
super(User)
}
@SwaggyList
def index(Integer max) {
super.index(max)
}
@SwaggyShow
def show() {
super.show()
}
@Transactional
@SwaggySave
def save() {
super.save()
}
@Transactional
@SwaggyUpdate
def update() {
super.update()
}
@Transactional
@SwaggyDelete
def delete() {
super.delete()
}
}
```
4. Run app
```bash
gradle bootRun
```
open http://localhost:8080/api