Every endpoint that accepts input in the request body needs a schema definition for the body parameter. Schema definitions are generated automatically with the @Endpoint validatorId attribute. This guarantees that swagger.json will always match what an endpoint actually accepts.
Similarly, every endpoint that generates a response body needs a schema definition associated with any success response code, such as 200 or 201. Response schema definitions are automatically generated with the @Endpoint filter attribute, or the validatorId attribute if the filterId is omitted. The schema is automatically associated with both the 200 and 201 response codes, if present.
Using both the tags in the payloadSchema.xml file and information that the payload schema framework determines by introspecting referenced repository items and Java objects at start up, a complete schema definition is automatically generated. This includes all property names, data types, required and writable attributes, alternate data models (such as switch/case combinations) and others. In most cases, no additional information is required. If an additional explanation of the schema is needed, the payload schema XML offers a doc tag that can be included as a child of the schema, property and bean-property tags. The doc tag uses PCDATA rather than an attribute for the text, which gets transferred to a description property in swagger.json. Descriptions support rich text using GFM syntax. For additional information on payload schemas, refer to the Working with the Payload Schema section.
The following is an example of a schema definition:
<schema id="cart-Default"> ... properties ... <doc>Provides commentary about the cart's default filter.</doc> </schema> <schema id="closenessQualifiers.id-Summary"> ... <bean-property name="upsellActions"> <property name="element" class="java.lang.String"/> <doc>Describes a list of upsell actions.</doc> </bean-property> </schema>
Use the following instructions to add Swagger annotation to your endpoints.
The
@Apiannotation marks a class as a Swagger resource or sub-resource. Add the annotation to your endpoint and specify a value attribute. Thevalueattribute groups resources, and is used during the construction of Swagger’s tags. The value that you defined for the@Pathannotation can be used, without the slash:@Path("/checkout")
@API(value = "/cart")
public class CartRestResource extends AbstractOrderRestResource {Add the
@ApiOperationannotation to all of the methods in your endpoint. You can add it as the last annotation in the list. Include information on applied filters and any security details:@Endpoint(id="/cart/checkout/#POST", isSingular = true, validatorId = "cart.checkout", filterId = "cart-Default")
@ApiOperation(value = "Checks out the current order in the cart.")
public Object login(If your endpoint is returning different codes, you can annotate them and add the corresponding annotation after the
@ApiOperation. All responses must be unique. If you create multiple responses with the same code, Swagger will randomly pick a response:@ApiResponses(value = { @ApiResponse(code = 400,
message = "Failure: Invalid ID supplied."),
@ApiResponse(code = 404, message = "Failure: Order not found.") })Once the method is annotated, you must annotate all of the incoming parameters. Use the
@ApiParamannotation. With this annotation, thevalueattribute describes incoming parameters. Mark all required parameters with therequired=trueattribute. Thenameattribute is optional:
The following is an example of Swagger annotation:
@Api(value = "/cart")
@POST
@Path("/checkout")
@Endpoint(id="/cart/checkout/#POST", isSingular = true, validatorId =
"cart.checkout", filterId="cart-Default")
@ApiOperation(value = "Checkout the current order in the cart.")
public RepresentationModel checkout(@QueryParam("allowEmptyOrders") Boolean
pAllowEmptyOrders, JSONObject pInputJson)
throws RestException, CommerceException, ServletException {
…
}
