The document provides an overview of Swagger, a tool for creating interactive API documentation, client SDK generation, and API discoverability. It outlines various tools and configurations associated with Swagger, including specifications for using Swagger UI and integrating Swagger within a Grails application. Additionally, the document details annotations and configurations required to enhance API documentation, including several examples of how to use these features effectively.

1. By Vijay Shukla (vijay@nexthoughts.com)

2. Agenda
Introduction
Tools
Example
Integration
Annotations
Examples
Question
1. Swagger is a simple yet powerful representation of your RESTful API.
1. With a Swagger-enabled API, you get interactive documentation,
client SDK generation and discoverability.
1. Swagger helps companies like Apigee, Getty Images, Intuit,
LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the
best possible services with RESTful APIs.
Introduction

3. Tools
Swagger UI
Use a Swagger
specification to drive
your API
documentation
Swagger Editor
An editor for designing
Swagger specifications
from scratch, using a
simple YAML structure
SDK Generators
Turn an API spec
into client SDKs or
server-side code
with Swagger
Codegen.
For More Details

4. Example/Use Case
PetStore

5. Integration
BuildConfig
Add dependency resolution url
Add dependencies
Config
Add URL for swagger
Add init parameter
Allow user agents
resource.groovy
Set initial parameter value
for well documentation of
swagger

6. BuildConfig Setting
repositories {
mavenRepo "http://repo1.maven.org/maven2/"
mavenRepo "http://maven.restlet.org"
}
dependencies {
compile 'io.swagger:swagger-core:1.5.8'
compile 'io.swagger:swagger-jaxrs:1.5.8'
runtime 'ch.qos.logback:logback-
classic:1.0.6'
}
plugins{
compile ":jaxrs:0.11"
}
Note:- It will be more preferable to add jaxrs jar into lib. Adding plugin will not work properly.

7. Config
org.grails.jaxrs.url.mappings = ['/api', '/swagger.*']
org.grails.jaxrs.provider.init.parameters = [
'com.sun.jersey.config.property.packages':
'io.swagger.sample.resource;io.swagger.sample.model;io.swagger.jaxrs.listing;io.swagger.jaxrs.json'
]
grails.mime.disable.accept.header.userAgents = []

8. resource.groovy
import io.swagger.jaxrs.config.BeanConfig
beans = {
swaggerConfig(BeanConfig) {
def serverUrl = grailsApplication.config.grails.serverURL.toString()
def hostName = serverUrl.substring(serverUrl.indexOf("://") + 3)
resourcePackage = 'com.nexthoughts'
host = hostName
version = 'v0' // Default "1".
title = 'Create your REST document' // Default: App Name.
description = 'API for Accessing secured resources'
contact = 'vijay@nexthoughts.com'
license = ''
licenseUrl = ''
}
}

9. Property of Swagger
Bean Config
setTitle(String) title Sets the title of the application.
setDescription(String) description Sets the description of the application.
setTermsOfServiceUr
l(String)
termsOfServ
iceUrl
Sets the URL of the application’s Terms of
Service.
setContact(String) contact
Sets the contact information for the
application.
setLicense(String) license Sets the license of the application
setLicenseUrl(String)
licenseUrl Sets the license URL of the application.
setVersion(String) version Sets the version of the API.
setBasePath(String) basePath Sets the basePath for the API calls.
setApiReader(String) apiReader Sets an API Reader class for Swagger.
setFilterClass(Sting) filterClass
Sets a security filter for Swagger’s
documentation.
setResourcePackage(String)
resourcePac
kage
Sets which package(s) Swagger should
scan to pick up resources. If there’s
more than one package, it can be a list
of comma-separated packages
setScan(boolean) scan
When set to true, Swagger will build
the documentation

10. Code to generate document of REST
String[] schemes = ["http"] as String[]
swaggerConfig.setSchemes(schemes)
swaggerConfig.setScan(true)
def swagger = swaggerConfig.getSwagger()
Json.mapper().writeValueAsString(swagger);

11. Annotations
Controller Annotation
@Api:- Marks a class as a Swagger resource.
@Path:- Uri to expose the controller.
Action Annotation
@GET, @POST, @PUT, @DELETE
@Path:- uri to access action
@ApiOperation:- Details of working of action and http
method against it
@Produces:- Produce the response formatting.
@Consumes:- Formatting data it will accept
@PathParam, @QueryParam, @HeaderParam, @FormParam
@BeanParam

12. More annotation
@ApiResponses:- A wrapper to allow a list of multiple ApiResponse objects.
@ApiResponse:- Describes a possible response of an operation.
@ApiParam:- Adds additional meta-data for operation parameters.
@ApiImplicitParams:- A wrapper to allow a list of multiple ApiImplicitParam objects.
@ApiImplicitParam:- Represents a single parameter in an API Operation.
@ApiModel:- Provides additional information about Swagger models.
@ApiModelProperty:- Adds and manipulates data of a model property.
@Authorization:- Declares an authorization scheme to be used on a resource or an operation.
@AuthorizationScope:- Describes an OAuth2 authorization scope.

13. Details of Annotations
@Api(
value=”uri”
description=”short notes”
consume=”format of data it will accept”
)
@ApiOperation(
value=”details”,
notes=”more details”
response=Class
nickName=”nickname”
)
@ApiResponse(
code=int
message=”detail of output”
)
@ApiParam(
value=”details”
required=boolean
)
@ApiImplicitParam(
name=”name of parameter”
value=”details”
required=boolean
dataType=”param datatype”
paramType=”param type”
)

14. More about annotations
Swagger-Sample
swagger website