Swagger uses a number of annotations to create and display documentation, with most Swagger annotations being with @API. A list of Swagger annotations can be found at https://github.com/swagger-api/swagger-core/wiki.
Note: You will only need few of the annotations and their attribute. The following descriptions focus on the Swagger features that are needed for endpoint design and implementation. Key features of the Swagger scan logic are described as they apply to Oracle Commerce REST endpoints.
When creating Swagger annotation, it is best to put the annotations after the JAX-RS and Oracle Commerce annotations. For example:
@Path("/currentUser")
@Api(value = "currentUser")
public class CurrentUserRestResource extends GenericService {The following is an example of a swagger.json file format:
{
"swagger" : "2.0",
"info" : {
"title" : "REST API Reference for Oracle Commerce Platform"
"version" : "v1"
},
"host" : "somehost:8080",
"basePath" : "/public/v1",
"tags" : [ {
"name" : "articles"
},
... ],
"schemes" : [ "http" ],
"paths" : {
"/" : {
"get" : {
"tags" : [ "version" ],
"summary" : "get version",
"description" : "Retrieves a singular version resource that pertains to
this context.",
"operationId" : "getVersion",
"parameters" : [ ],
"responses" : {
"200" : {
"description" : "successful operation",
"schema" : {
"$ref" : "#/definitions/version-Default"
}
},
"500" : {
"description" : "Invalid version resource path."
}
}
}
},
"/cart" : {
"get" : {
"tags" : [ "cart" ],
"operationId" : "getCurrentOrder",
"responses" : {
"200" : {
"description" : "successful operation",
"schema" : {
"$ref" : "#/definitions/cart-Summary"
},
"headers" : { }
}
}
},
"delete" : {
"tags" : [ "cart" ],
"summary" : "Cancels the current order.",
"description" : "Cancels the current order.",
"operationId" : "cancelCart",
"parameters" : [ ],
"responses" : {
"500" : {
"description" : "Could not cancel the order."
}
}
}
},
...
},
"definitions" : {
"orders.id-Summary" : {
"properties" : {
"id" : {
"type" : "string"
},
"totalCommerceItemCount" : {
"type" : "integer",
"format" : "int64"
},
"totalCommerceItemCountWithFraction" : {
"type" : "number",
"format" : "double"
},
"priceInfo" : {
"$ref" : "#/definitions/orders.id.orderPriceInfo-Summary"
},
"commerceItems" : {
"$ref" : "#/definitions/commerceitems-CollectionSummary"
}
}
},
"promotions.id-Default" : {
"$ref" : "#/definitions/promotions.id-Summary"
},
...
}
}The main Swagger annotation is @Api which marks a class as a Swagger resource or sub-resource. @Api must be used within resource and sub-resource classes for their endpoints to appear in general documentation.
Tags group endpoints, with the scan automatically using the value of the @Api value attribute as a tag for every endpoint in the class; if the value starts with “/”, the slash is removed. You can use the same value for the value property in both @Path and @Api annotations. Sub-resource endpoints are automatically tagged with their own tags and their ancestor resources’ tags. Should you prefer not to use the value attribute, you can specify the tags attribute to add a list of tags.
A method in a resource or sub-resource class is considered to be an endpoint if it contains a JAX-RS @Path annotation. It must also have an HTTP method annotation, which is a JAX-RS @GET, @DELETE, @POST, @PUT, or an Oracle Commerce @PATCH. The @ApiOperation annotation is not required for an endpoint to be included in swagger.json. However, it does provide a place to specify useful information that cannot be determined in other ways. Endpoints should use the @ApiOperation value attribute to specify a summary of the actions that an endpoint performs.
Swagger adds an entry to its paths section for each unique path, building the path identifier from the endpoint @Path, the class @Path, and any ancestor resource path. Each HTTP method corresponds to an operation under the path. Each endpoint is represented in swagger.json with a path and operation pair.
