代码优先还是设计优先?说说API开发技术(八)

举报
Jet Ding 发表于 2021/07/26 10:01:34 2021/07/26
【摘要】 代码案例: @Api(tags = "Member API")@CrossOrigin@Controller@RequestMapping(value = "/members", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)public class MemberController { private MemberService m...

代码案例:

 

@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);

    }

}

运行效果:

 

89.png

展开以后的效果:

90.png

 

RAML

89.jpg

 


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

 

一个例子:

 

88.png


 

一些亮点:

 

l  712行:定义特征,在多处引用

l  12行:Include一个文件

l  1314行:定义一个 "资源 "数据类型"/songs";使用以前定义的特征。

l  151937行:定义了HTTP方法。

l  2536行:MIME类型。

 

API Blueprint

 

87.png


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开发方法时,应该先尝试回答上面的问题。

 

欢迎讨论。

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。