easily generate docs and playground for your RESTful API


Email StackOverflow

Annotation to document API flows

Suppose you want to document a flow of calls to your API methods to achieve a goal, for example, the flow of methods to subsequently call in order to purchase a book in a library application. With @Api, @ApiMethod and @ApiObject you can document single methods but these methods will be likely used to perform complex actions. You can document API flows with the @ApiFlow annotation. For example:

package org.jsondoc.sample.flow;

import org.jsondoc.core.annotation.ApiFlow;
import org.jsondoc.core.annotation.ApiFlowSet;
import org.jsondoc.core.annotation.ApiFlowStep;

public class BookFlows {
		name = "Book purchase flow",
		description = "The flow for purchasing a book",
		preconditions = {
				"To purchase a book there must be an existing user",
				"The user must have an account with username and password",
				"The user must have the role needed to purchase books"
		steps = {
			@ApiFlowStep(apimethodid = FlowConstants.USER_LOGIN_METHOD_ID),
			@ApiFlowStep(apimethodid = FlowConstants.BOOK_LIST_METHOD_ID),
			@ApiFlowStep(apimethodid = FlowConstants.BOOK_OBJECT_METHOD_ID),
			@ApiFlowStep(apimethodid = FlowConstants.BOOK_PURCHASE_METHOD_ID)
	public void bookPurchaseFlow() {
		name = "Similar books flow",
		description = "The flow for getting books similar to a given book",
		steps = {
			@ApiFlowStep(apimethodid = FlowConstants.BOOK_OBJECT_METHOD_ID),
			@ApiFlowStep(apimethodid = FlowConstants.BOOK_SIMILAR_METHOD_ID)
	public void similarBooksFlow() {


The @ApiFlowSet annotation informs JSONDoc that the class contains a set of flows to be documented. Each flow is then declared on a method in the class using the @ApiFlow annotation, which has some properties to better document the flow, in particular the steps property, made of @ApiFlowStep annotations.

The apimethodid property is very important and mandatory, because it defines which method, documented with @ApiMethod, this step is referring to. Thus, if you want to document API flows, then you need to set the same id on both @ApiMethod and @ApiFlowStep. My suggestion is to put the IDs in a constants class, and refer those IDs in the two annotations. For example, here is an example class with IDs:

package org.jsondoc.sample.flow;

public class FlowConstants {

	// User service
	public static final String USER_LOGIN_METHOD_ID = "USER_LOGIN";

	// Book service
	public static final String BOOK_LIST_METHOD_ID = "BOOK_LIST";
	public static final String BOOK_OBJECT_METHOD_ID = "BOOK_OBJECT";
	public static final String BOOK_PURCHASE_METHOD_ID = "BOOK_PURCHASE";
	public static final String BOOK_SIMILAR_METHOD_ID = "BOOK_SIMILAR";

The value of these constants is not important. The important thing is that you have the same value on both the @ApiMethod id property and the @ApiFlowStep apimethodid property.

Version 1.2.17 | Licensed under MIT License

GitHub Project | Issues