系统分析与设计-homework3(lesson5)

API Blueprint笔记

Blueprint 是什么

Blueprint是一种用来编写API文档的标记语言，语法与markdown相似，apiaryio提供实时预览功能，使web api的书写更加便捷规范，与其他一些工具配合，可以直接生成mock data数据，只要和后端开发人员约定好接口及数据结构，前端在开发的时候就可以使用mock data数据进行测试，使得前后端开发能够同时进行。

Blueprint 如何使用

• 关联github账号
  官网地址：https://apiary.io/
  
  
  
  
• 关联仓库
  成功关联仓库后就可以编写Blueprint API文档了。
• 语法
  前面提到Blueprint语法与markdown相似，详细的语法及编写规范可查看官方教程： Tutorial
• 例子
  下面我们编写一个简单的例子供大家参考：

FORMAT: 1A
HOST: http://myFirstBluePrint.apiblueprint.org/

#  myBluePrint

my first blueprint API

##  Test1 [/test]

### get menu [GET]

+ Response 200 (application/json)

        [
            {
                "name" : "chicken",
                "type" : "food"
            },
            {
                "name" : "cola",
                "type" : "drink"
            }
        ]

• FORMAT: 指明使用的版本
• HOST: 资源所在的URL地址
• # 为标题，#、##、###不同等级的标题
  
  • # ：一级标题，指明API文档名，组名，程序入口点
  • ##：二级标题，指明路径模板，方法名
  • ###：三级标题，指明方法名
  • +无序列表，与Request, Response, Parameters, Model等关键字组合使用
• 其他关键字
  
  • GET：http中的get方法
  • POST：http中post方法
  • PUT：http中put方法
  • PATCH：http中patch方法
  • DELETE：http中delete方法
  • Request：请求体的类型，内容
  • Response：响应体的响应码，内容
  • Parameters：指明参数
  • Model：指明应当返回的内容
    
    将我们上面的例子写到 apiaryio 的编辑器上
    
    
    
    可以看到右方有预览窗口，点击get menu后可以看到该部分的逻辑方法
    
    
    
    使用mock sever生成mock data进行测试
    
    
    打开生成的url，可以看到我们希望返回的数据