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 ;

}