文档章节

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

麦拂沙
 麦拂沙
发布于 2017/02/12 16:58
字数 448
阅读 35
收藏 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
博文 112
码字总数 100094
作品 1
海淀
高级程序员
2016年2月17日:可测试化的文档

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

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

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

loowj
2011/11/06
0
0
百度贴吧:解读超量级LAMP架构

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

rtdot
2011/12/05
0
0
非 RESTful 的微软 REST API 指南

微软发布了创建“RESTful” API的指南。Roy Fielding将这些与REST没有多大关系的API称为HTTP API。 许多组织都发布了创建面向Web的HTTP API的建议,甚至是白宫都发布了一份标准——“白宫Web...

oschina
2016/07/31
4.9K
8
OpenAPI 规范 3.0 版接近最终发布

“开放 API 战略” (Open API Initiativev) 发布了 OpenAPI 规范 3.0 版的预览,并规划于今年二月底发布实施草案(Implementer Draft)。 新的 OpenAPI 规范 3.0 带来了如下重大改进: 为实现...

局长
2017/02/07
2.4K
7

没有更多内容

加载失败,请刷新页面

加载更多

spring只

一、IOC(Inversion of Control)或者依赖注入(Dependency Injection) 1、底层实现原理:反射 2、三大核心接口: BeanFactory:简单容器系列,只是实现了容器最基本的功能。 ApplicationC...

狠一点
9分钟前
3
0
缓存架构SpringBoot集成Curator实现zookeeper分布式锁

一、分布式锁简介 1、什么是锁 在单机环境下,当存在多个线程可以同时改变某个共享变量时,就需要同步来实现该功能,使其线程安全。 而同步就是通过锁来实现的。锁保证了同一时刻只有一个线程...

架构师springboot
11分钟前
0
0
11《Java核心技术》之Java提供了哪些IO方式? NIO如何实现多路复用?

一、提出问题 IO 一直是软件开发中的核心部分之一,伴随着海量数据增长和分布式系统的发展,IO 扩展能力愈发重要。幸运的是,Java 平台 IO 机制经过不断完善,虽然在某些方面仍有不足,但已经...

飞鱼说编程
18分钟前
0
0
简单介绍Java 的JAR包、EAR包、WAR包区别

WAR包 WAR(Web Archive file)网络应用程序文件,是与平台无关的文件格式,它允许将许多文件组合成一个压缩文件。War专用于Web方面。大部分的JAVA WEB工程,都是打成WAR包进行发布的。 War是...

linuxprobe16
18分钟前
0
0
55:Mysql用户管理|常用sql语句|mysql数据库备份恢复

1、Mysql用户管理; 场景,为了安全,新建的站点,创建新的用户,或者给已有用户授权,对某个库或者某个表有权限; 语法: grant all on *.* to 'user'@'127.0.0.1' identified by 'password'; g...

芬野de博客
22分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部