swagger and restful api 参考

 

http://git.oschina.net/redArmy/spring-cloud-books/blob/master/spring-cloud-provider-book/src/main/java/com/wujunshen/controller/BookController.java
    /**
     * @param book 传入的book对象实例 

* @return 成功或失败信息，json格式封装 

*/ 

@PostMapping(value = "/api/books", consumes = MediaType.APPLICATION_JSON_UTF8_VALUE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE) 

@ApiOperation(value = "添加某本书籍", httpMethod = "POST", 

notes = "添加成功返回bookId", 

response = BaseResultVo.class 

) 

@ApiResponses(value = { 

@ApiResponse(code = 200, message = "Success", response = BaseResultVo.class), 

@ApiResponse(code = 401, message = "Unauthorized"), 

@ApiResponse(code = 403, message = "Forbidden"), 

@ApiResponse(code = 404, message = "Not Found"), 

@ApiResponse(code = 500, message = "Failure")}) 

public BaseResultVo saveBook(@Validated @ApiParam(value = "添加的某本书籍信息", required = true) @RequestBody Book book) { 

BaseResultVo baseResultVo = new BaseResultVo(); 

baseResultVo.setData(bookService.saveBook(book)); 

baseResultVo.setCode(ResultStatusCode.OK.getCode()); 

baseResultVo.setMessage(ResultStatusCode.OK.getMessage()); 

return baseResultVo; 

} 

/** 

* @return 成功或失败信息，json格式封装 

*/ 

@GetMapping(value = "/api/books", produces = MediaType.APPLICATION_JSON_UTF8_VALUE) 

@ApiOperation(value = "查询所有书籍", httpMethod = "GET", 

notes = "查询所有书籍", 

response = BaseResultVo.class 

) 

@ApiResponses(value = { 

@ApiResponse(code = 200, message = "Success", response = BaseResultVo.class), 

@ApiResponse(code = 401, message = "Unauthorized"), 

@ApiResponse(code = 403, message = "Forbidden"), 

@ApiResponse(code = 404, message = "Not Found"), 

@ApiResponse(code = 500, message = "Failure")}) 

public BaseResultVo getBooks() { 

Books books = bookService.getBooks(); 

BaseResultVo baseResultVo = new BaseResultVo(); 

if ((books != null) && (!books.getBookList().isEmpty())) { 

baseResultVo.setData(books); 

baseResultVo.setCode(ResultStatusCode.OK.getCode()); 

baseResultVo.setMessage(ResultStatusCode.OK.getMessage()); 

} else { 

baseResultVo.setCode(ResultStatusCode.DATA_QUERY_ERROR.getCode()); 

baseResultVo.setData("Query books failed"); 

baseResultVo.setMessage(ResultStatusCode.DATA_QUERY_ERROR.getMessage()); 

} 

return baseResultVo; 

} 

/** 

* @param bookId 传入的bookId 

* @return 成功或失败信息，json格式封装 

*/ 

@GetMapping(value = "/api/books/{bookId:[0-9]*}") 

@ApiOperation(value = "查询某本书籍", httpMethod = "GET", 

notes = "根据bookId，查询到某本书籍", 

response = BaseResultVo.class 

) 

@ApiResponses(value = { 

@ApiResponse(code = 200, message = "Success", response = BaseResultVo.class), 

@ApiResponse(code = 401, message = "Unauthorized"), 

@ApiResponse(code = 403, message = "Forbidden"), 

@ApiResponse(code = 404, message = "Not Found"), 

@ApiResponse(code = 500, message = "Failure")}) 

public BaseResultVo getBook(@ApiParam(value = "书籍ID", required = true) @PathVariable("bookId") Integer bookId) { 

LOGGER.info("请求参数bookId值：{}", bookId); 

Book book = bookService.getBook(bookId); 

BaseResultVo baseResultVo = new BaseResultVo(); 

if (book != null) { 

LOGGER.info("查询到书籍ID为{}的书籍", bookId); 

baseResultVo.setData(book); 

baseResultVo.setCode(ResultStatusCode.OK.getCode()); 

baseResultVo.setMessage(ResultStatusCode.OK.getMessage()); 

} else { 

LOGGER.info("没有查询到书籍ID为{}的书籍", bookId); 

baseResultVo.setCode(ResultStatusCode.DATA_QUERY_ERROR.getCode()); 

baseResultVo.setData("Query book failed id=" + bookId); 

baseResultVo.setMessage(ResultStatusCode.DATA_QUERY_ERROR.getMessage()); 

} 

return baseResultVo; 

} 

@PutMapping(value = "/api/books/{bookId:[0-9]*}") 

@ApiOperation(value = "更新某本书籍", httpMethod = "PUT", 

notes = "更新的某本书籍信息", 

response = BaseResultVo.class 

) 

@ApiResponses(value = { 

@ApiResponse(code = 200, message = "Success", response = BaseResultVo.class), 

@ApiResponse(code = 401, message = "Unauthorized"), 

@ApiResponse(code = 403, message = "Forbidden"), 

@ApiResponse(code = 404, message = "Not Found"), 

@ApiResponse(code = 500, message = "Failure")}) 

public BaseResultVo updateBook(@NotNull @ApiParam(value = "要更新的某本书籍ID", required = true) @PathVariable("bookId") Integer bookId, @Validated @NotNull @ApiParam(value = "要更新的某本书籍信息", required = true) @RequestBody Book book) { 

LOGGER.info("请求参数bookId值：{}", bookId); 

BaseResultVo baseResultVo = new BaseResultVo(); 

if (bookId == null && book == null) { 

baseResultVo.setCode(ResultStatusCode.DATA_INPUT_ERROR.getCode()); 

baseResultVo.setMessage(ResultStatusCode.DATA_INPUT_ERROR.getMessage()); 

return baseResultVo; 

} 

if (bookService.getBook(bookId) == null) { 

baseResultVo.setCode(ResultStatusCode.DATA_QUERY_ERROR.getCode()); 

baseResultVo.setData("book id=" + bookId + " not existed"); 

baseResultVo.setMessage(ResultStatusCode.DATA_QUERY_ERROR.getMessage()); 

return baseResultVo; 

} 

Book updatedBook = bookService.updateBook(book); 

if (updatedBook != null) { 

baseResultVo.setData(updatedBook); 

baseResultVo.setCode(ResultStatusCode.OK.getCode()); 

baseResultVo.setMessage(ResultStatusCode.OK.getMessage()); 

} else { 

baseResultVo.setCode(ResultStatusCode.DATA_UPDATED_ERROR.getCode()); 

baseResultVo.setData("Update book failed id=" + book.getBookId()); 

baseResultVo.setMessage(ResultStatusCode.DATA_UPDATED_ERROR.getMessage()); 

} 

return baseResultVo; 

} 

@DeleteMapping(value = "/api/books/{bookId:[0-9]*}") 

@ApiOperation(value = "删除某本书籍信息", httpMethod = "DELETE", 

notes = "删除某本书籍信息", 

response = BaseResultVo.class 

) 

@ApiResponses(value = { 

@ApiResponse(code = 200, message = "Success", response = BaseResultVo.class), 

@ApiResponse(code = 401, message = "Unauthorized"), 

@ApiResponse(code = 403, message = "Forbidden"), 

@ApiResponse(code = 404, message = "Not Found"), 

@ApiResponse(code = 500, message = "Failure")}) 

public BaseResultVo deleteBook(@ApiParam(value = "要删除的某本书籍ID", required = true) @PathVariable("bookId") Integer bookId) { 

BaseResultVo baseResultVo = new BaseResultVo(); 

if (bookService.deleteBook(bookId) == 1) { 

baseResultVo.setData("Deleted book id=" + bookId); 

baseResultVo.setCode(ResultStatusCode.OK.getCode()); 

baseResultVo.setMessage(ResultStatusCode.OK.getMessage()); 

} else { 

baseResultVo.setCode(ResultStatusCode.DATA_DELETED_ERROR.getCode()); 

baseResultVo.setData("Deleted book failed id=" + bookId); 

baseResultVo.setMessage(ResultStatusCode.DATA_DELETED_ERROR.getMessage()); 

} 

return baseResultVo; 

}