Exposing REST Services Using Swagger

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

First thing you need to do when you use Swagger is use @Api annotation for describe endpoint.

Selection_061

Next thing need to add is @ApiOperation annotation. This will create a UI for the API.

Selection_062

Above annotation will create a following UI for you, You are building the documentation UI while you are creating the API. You don’t have to create a separate documentation.

Selection_063

Then you can add errors for rest api usage.

Selection_064

If some one wants to add specific value and test the api, you can implement it in documentation by @ApiParam annotation. All the details of the parameter can be describe in this doc too.

Selection_065

This is the full api code wrap with Swagger annotation.

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

import com.example.model.Account;
import com.example.service.AccountService;
import com.force.api.ApiException;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiError;
import com.wordnik.swagger.annotations.ApiErrors;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;

@Controller
@RequestMapping(value = "/api/v1/account")
@Api(value = "Account operations", listingClass = "AccountController", basePath = "/api/v1/account", description = "All operations for accounts")
public class AccountController {
	
	@Autowired
	AccountService accountService;
	
	@ApiOperation(value = "Get all account (max:200)", notes = "Get all existing account names (max:200)", httpMethod = "GET", responseClass = "Account", multiValueResponse = true)
	@ApiError(code = 500, reason = "Process error")
	@RequestMapping(value = "/", method = RequestMethod.GET, produces = "application/json")
	public @ResponseBody List<Account> showAllAccounts() throws ApiException  {
	    return accountService.listAccounts();
	}
	
	@ApiOperation(value = "Get a existing account by Id", notes = "Get account name by specifying a Salesforce account id", httpMethod = "GET", responseClass = "Account", multiValueResponse = true)
	@ApiErrors(value = { @ApiError(code = 400, reason = "Invalid Id supplied"), @ApiError(code = 404, reason = "Account not found") })
	@RequestMapping(value = "/find/{accountId}", method = RequestMethod.GET, produces = "application/json")
	public @ResponseBody Account findAccountById(@ApiParam(internalDescription = "java.lang.string", name = "accountId", required = true, value = "string") @PathVariable String accountId) throws ApiException {
		return accountService.findAccountById(accountId);
    }
	
	@ApiOperation(value = "Delete a account giving an Id", notes = "Delete a account by specifying a Salesforce account id", httpMethod = "DELETE")
    @ApiError(code = 500, reason = "Process error")
    @RequestMapping(value = "/delete/{accountId}", method = RequestMethod.DELETE, produces = "application/json")
	public @ResponseBody String deleteAccount(@ApiParam(internalDescription = "java.lang.string", name = "accountId", required = true, value = "string") @PathVariable String accountId) throws ApiException {
		return accountService.deleteAccount(accountId);
    }
	
	@ApiOperation(value = "Create a new account", notes = "Creates a new Salesforce account by specifying a account name", httpMethod = "POST")
    @ApiError(code = 500, reason = "Process error")
    @RequestMapping(value = "/new", method = RequestMethod.POST, produces = "application/json")
	public @ResponseBody String createAccountFromParamName(@ApiParam(internalDescription = "java.lang.string", name = "name", required = true, value = "string") @RequestParam(required = true) String name) throws ApiException{	
		return accountService.createAccount(name);
    }
	
	@ApiOperation(value = "Update an exsiting account by Id", notes = "Update a existing account by specifying a Salesforce id", httpMethod = "POST")
	@RequestMapping(value = "/update/{accountId}", method = RequestMethod.POST, produces = "application/json")
	public @ResponseBody String updateAccount(@PathVariable(value="accountId") String accountId, @ApiParam(internalDescription = "java.lang.string", name = "name", required = true, value = "string") @RequestParam(required = true) String name) throws ApiException {
		Account updateAccount = new Account();
		updateAccount.setName(name);
		return accountService.updateAccount(accountId, updateAccount);
	}
}

This will create the following documentation UI.
Selection_066Lets try to create a new account and test the API. Click ‘try it out’ after providing the name parameter. Selection_067

It will shows the response body,code and any headers for the invoking above rest operation.
Selection_069I guess this would help you to get rough idea about Swager tool for API documentation. You can find complete project here

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s