代码案例：

 

@Api(tags = "Member API")

@CrossOrigin

@Controller

@RequestMapping(value = "/members", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

public class MemberController {

    private MemberService memberService;

 

    public MemberController(@Lazy MemberService memberService) {

        this.memberService = memberService;

    }

 

    @ApiOperation(value = "Retrieves member information as filtered by an optional search string or filter request")

    @ApiResponses(value = { @ApiResponse(code = SC_OK, message = "ok") })

    @ResponseBody

    @GetMapping(value = "")

    @ResponseStatus(HttpStatus.OK)

    public ResponseEntity<List<Member>> getAllMembers(@RequestParam(required = false) String searchString, FilterRequest filter) {

        return new ResponseEntity<>(memberService.getMembers(filter, searchString), HttpStatus.OK);

    }

}

运行效果：

展开以后的效果：

【RAML】

REST API建模语言（RAML）是一种基于YAML的描述REST API的语言，它提供了描述REST或实际REST API所需的所有信息。虽然RAML是为REST API设计的，但它能够描述不服从REST的所有约束的API（因此被称为 "practically RESTful"）。它鼓励重用，以最佳实践结果为目标。

一个例子：

一些亮点：

l  第7、12行：定义特征，在多处引用

l  第12行：Include一个文件

l  第13、14行：定义一个 "资源 "数据类型"/songs"；使用以前定义的特征。

l  第15、19、37行：定义了HTTP方法。

l  第25、36行：MIME类型。

【API Blueprint】

API Blueprint是一种高级的API描述语言。你可以用它在API开发之前设计一个API，或者描述一个现有的API。

一个例子：

FORMAT: 1A

 

# Categories API

 

## Categories [/categories]

 

### Create a Category [POST]

+ Response 201

 

## Category [/category/{id}]

+ Parameters

    + id: 42 (required)

 

### Delete a Category [DELETE]

+ Response 204

 

## Category Items [/category/{id}/items]

+ Parameters

    + id: 42 (required)

 

## Create an Item [POST]

+ Response 201

【小结】

在本文中，一共探讨了三种API设计技术： OpenAPI, RAML, API Bllueprint。我们重点从两个方向学习了OpenAPI技术：

l  先设计API, 再从API配置文件生成客户端和服务器端的代码,也就是设计优先的方法。

l  先写出代码实现，再从代码生成API文档，也就是代码优先的方法。

这两种方法都有利有弊。在开发API时到底应该选哪种方法？这主要取决于如下的因素：

l  谁会使用你的API？

l  他们的需求是什么？

l  API要解决什么问题？

l  谁来开发？

l  以后谁来维护？

在你选择正确的API开发方法时，应该先尝试回答上面的问题。

欢迎讨论。