文档章节

基于RAML的接口描述规范 及 Doc&Mock服务构建

麦拂沙
 麦拂沙
发布于 2017/02/12 16:58
字数 448
阅读 50
收藏 0

示例

  1. 主配置文件(./api.yaml)
#%RAML 1.0
title: API Document
baseUri: https://api.example.com
protocols: [ HTTPS ]
mediaType: application/json

pageable: !include ./traits/pageable.raml

types:
  PostBookJson:
    type: object
    properties:
      name:
        type: string
        description: 名字
        required: true
  BookJson:
    type: PostBookJson
    properties:
      id:
        type: integer
        description: 主键
        required: true

/books:
  displayName: book列表资源
  get:
    description: 获取book资源列表
    is: pageable
    queryParameters:
      name: string
    responses:
      200:
        body:
          application/json:
            type: BookJson[]
  post:
    description: 创建book资源
    body:
      application/json:
        type: PostBookJson
    responses:
      201:
        body:
          application/json:
            type: BookJson
      422:
        body:
          application/json:
            example:
              error: validation_failed
              error_description: name is required
  /{id}:
    displayName: book详情资源
    get:
      description: 获取book详情
      queryParameters:
        id: integer
        name: string
      responses:
        200:
          body:
            application/json:
              type: BookJson
    put:
      description: 修改book资源
      body:
        application/json:
          type: PostBookJson
      responses:
        200:
          body:
            application/json:
              type: BookJson
        404:
          body:
            application/json:
              example:
                error: resource not found
                error_description: The book you requested was not found
        422:
          body:
            application/json:
              example:
                error: valication failed
                error_description:  name must be filled
    delete:
      description: 删除book资源
      responses:
        204:
          body: !!null
        404:
          body:
            application/json:
              example:
                error: resource not found
                error_description: The book you requested was not found
  1. 引用文件(./traits/pageable.raml)
description: common page trait, resource can be paged defaultly
queryParameters:
  page:
    description: Specify the page that you want to retrieve
    type: number
    required: false
    default: 1
    maximum: 1000
    example: 1
  per_page:
    description: Specify the amount of items that will be retrieved per page
    type: number
    required: false
    default: 20
    maximum: 100
    example: 20
  sort:
    description: Specify the sort order of the items list, + mean asc, - mean desc
    type: string
    required: false
    default: -id
    example: +name,-id

responses:
  200:
    headers:
      Link:
        description: The paginator link according to https://tools.ietf.org/html/rfc5988
        type: string
        example: |
          '<https://api.example.com/api/users?page=1&per_page=20>; rel="first", <https://api.example.com/api/users?page=2&per_page=20>; rel="prev", <https://api.example.com/api/users?page=4&per_page=20>; rel="next", <https://api.example.com/api/users?page=50&per_page=20>; rel="last"'
      X-Total-Count:
        description: 分页列表数据总计
        type: number
        example: 1000

基于RAML构建文档服务

sudo cnpm install -g raml2html

raml2html -i api.raml -o index.html 【-t /templates/自定义模板.nunjucks】
# 或者
raml2html 【-t /templates/自定义模板.nunjucks】api.raml > index.html

基于RAML构建Mock服务

sudo cnpm install -g localapi

pkill -f /usr/local/bin/localapi
localapi run api.raml -p 8000 --no-examples <&- >&- 2>&- & disown

© 著作权归作者所有

共有 人打赏支持
麦拂沙
粉丝 22
博文 113
码字总数 100137
作品 1
海淀
高级程序员
私信 提问
2016年2月17日:可测试化的文档

有轻微雾霾 分布式服务中,对接其它服务的接口是家常便饭。对接之前需要了解对方的接口如何使用。常见的了解方式就是看文档,但文档是用来查看的,并不是被用来直接使用的。所以需要对照着文...

编走编想
2016/02/18
44
0
SCA、SOA与OSGi概念浅析

基于组件的编程一直是软件业简化编程和提高效率和质量的一个重要方法,但是往往对于不同语言我们有不同的组件模型,从而需要不同的调用方式。SCA的目的是使用户在构建企业应用时有一个不再直...

loowj
2011/11/06
0
0
14 个开源 REST 与 SOAP 服务 API 测试工具

当我们朝着更多敏捷的左移[译者注:左移测试]软件开发过程发展,比如持续集成和持续交付,需要不断增加对开发人员的快速反馈。 UI 测试的不足之处在于它们很慢,它很难让开发人员快速了解到他...

oschina
2017/06/17
7.5K
6
Web Service - RESTful 和 SOAP 笔记

1.什么是Web Service(Web服务) 从表面上看,Web Service就是一个应用程序,它向外界暴露出一个能够通过Web进行调用的API。 这就是说,你能够用编程的方法透明的调用这个应用程序,不需要了...

6pker
2015/12/02
220
4
百度贴吧:解读超量级LAMP架构

【IT168 技术】贴吧是功能性产品,唯快不破是永恒的准则,这一特点决定了快速迭代是需要解决的关键性问题。快速迭代,分解开来有如下部分:开发阶段,快速开发;测试阶段,包含了环境快速搭建...

rtdot
2011/12/05
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Jmeter参数的AES加密使用

在Jmeter日常实践中,大家应该都遇到过接口传参需要加密的情况。以登陆为例,用户名和密码一般都需要进行加密传输,在服务端再进行解密,这样安全系数会更高,但在使用jmeter进行接口测试的时...

程序猿拿Q
10分钟前
0
0
MYSQL 日期函数 Date and Time Functions

Table 12.13 Date and Time Functions Name Description ADDDATE() Add time values (intervals) to a date value ADDTIME() Add time CONVERT_TZ() Convert from one time zone to another ......

_liucui_
17分钟前
0
0
Android代码混淆ProGuard工作原理简介

ProGuard能够对Java类中的代码进行压缩(Shrink),优化(Optimize),混淆(Obfuscate),预检(Preveirfy)。    1. 压缩(Shrink): 在压缩处理这一步中,用于检测和删除没有使用的类,字段...

SuShine
19分钟前
0
0
Idea 2018激活

教程地址: https://www.52pojie.cn/thread-781394-1-1.html 亲测可用

一个不正经的程序员
25分钟前
0
0
Android组件化开发实践和案例分享

目录介绍 1.为什么要组件化 1.1 为什么要组件化 1.2 现阶段遇到的问题 2.组件化的概念 2.1 什么是组件化 2.2 区分模块化与组件化 2.3 组件化优势好处 2.4 区分组件化和插件化 2.5 applicatio...

潇湘剑雨
25分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部