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; 
    }