使用Ruby项目Slate 构建API文档服务,漂亮的API文档
查看原文请到我的个人网站 兵哥的领悟
最近工作需要,为兄弟部门提供若干服务接口,遂需要编写API文档,供兄弟部门使用,经同事推荐 使用 slate最为编写和运行在线文档的服务,使用之后,发现还不错,这里记录一下。
上图来自官网,官网上说 slate 配置简单、干净、上手快等等好处,等不及要试试了。
首先第一步,需要安装Ruby,已经有安装过的朋友直接跳过这一步吧!
1)从官网下载源码或者安装包 http://www.ruby-lang.org/en/downloads/ 下载Source Code或者RubyInstaller 从 http://rubyinstaller.org/downloads/下载RubyInstaller
slate 上面说选择1.9.3或更新的版本。
2)安装Ruby,选择下一步,安装到合适的目录就行了,这里略掉了,安装完成后然后设置环境变量如下,运行ruby -v 显示版本号则安装完成了。
gem install bundler
如果出现问题就先安装 json 的依赖,如果有问题,可以联系我
第三步,安装好Ruby 和Bundler 之后,就去slate下载包,如果你本地安装了Github客户端可以直接clone下来,如果不是就去下载后解压到本地合适目录。打开cmd cd到刚才解压的slate目录里面,运行 bundle install 然后运行服务。记得一定要在slate目录下面。
在浏览器里面敲如 http://localhost:4567 即可出现需要的api文档。
如何编辑呢?打开slate\source\includes 下面 你会发现一个_errors.md 的文件,你猜对了,他就是用来写api的,你复制一个重命名为_user.md(任意名称,但要下划线开头)
然后在里面编辑如我的demo,然后在slate\source目录下的index.md 下面加入
includes:
- errors
加入后
includes:
- errors
- video
你可以把errors模块去掉,实现自定义一下是我的模版。
[code]# 欢乐课堂接口 ## 1.3 获取筛选数据 ```Java 略 ``` > 返回的JSON示例: ```json { ["1": { grade:{1:"一年级"……}, semester:[上册,下册], publish:{1:"人民邮电出版社",2:"清华大学出版社"……} }, "2": { grade:{1:"一年级"……}, semester:[上册,下册], publish:{1:"人民邮电出版社",2:"清华大学出版社"……} }], updateTime : 172394433 } ``` ### HTTP 请求 `GET /queryFilterData` ### 请求参数 参数 | 必选 | 默认 | 字段类型 | 字段说明 --------- | ------- | ------- | -------- | ---------- 无 ### 返回字段说明 参数 | 字段类型 | 字段说明 --------- | ----------- | ----------- status | string | 状态,有success和fail filterData | String | json格式的字符串 updateTime | long | 最后更新时间 ## 1.6 获取视频列表 ```Java 略 > 返回的JSON示例: ```json [ { "videoId": "1", "videoImgUrl" : "http://xxx.com/asd.png", "videoKnowdge","全等三角形" }, { "videoId": "2", "videoImgUrl" : "http://xxx.com/asd.png", "videoKnowdge","全等三角形" }, ] ``` 根据科目、年级、出版社信息获取视频列表。每本教材的根节点中必须包含此教材最后更新的日期,以便小机端更新本地缓存。 ### HTTP 请求 `GET /queryVideos` ### 请求参数 参数 | 必选 | 默认 | 字段类型 | 字段说明 --------- | ------- | ------- | -------- | ---------- uid | true | null | string | 用户账号 subjectId | true | 0 | Integer | 科目ID sectionId | true | 0 | Integer | 学段ID gradeId |true | 0 | Integer | 年级ID publishId |true | 0 | Integer | 出版社ID ### 返回字段说明 参数 | 字段类型 | 字段说明 --------- | ----------- | ----------- videoId | String | 视频编号 videoImgUrl | String | 视频封面链接 videoKnowdge | String | 视频知识点,可带多个知识点效果如图,怎么写大家自己领悟吧
阅读更多
- 第8章-使用Express.js和Hapi构建Node.js-REST-API服务-8.2.项目依赖
- Node.js项目实战-构建可扩展的Web应用(第一版):8 使用Express.js和Hapi构建Node.js REST API服务
- 使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【九】——API变了,客户端怎么办?
- 使用Office System构建基于项目的文档管理系统的设想
- 实践指南:使用SpringBoot构建API后端服务 上
- 使用Mkdocs构建你的项目文档
- 使用Swagger2构建RESTful API文档遇到的坑
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring Boot中使用Swagger2构建RESTful API文档
- 使用Javadoc导出项目的API文档
- SpringBoot开发详解(八) -- 使用Swagger2构建API文档
- 使用Laravel5.6+Passsport 构建Api项目
- 构建简单的 C++ 服务组件,第 2 部分: 通过服务组件体系结构使用 Python、Ruby 和 Web 服务
- Spring Cloud Spring Boot mybatis分布式微服务云架构(十)使用Swagger2构建强大的RESTful API文档(2)
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- 你不知道的Eclipse用法:使用Javadoc导出项目的API文档
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- SpringBoot入门——使用Swagger构建Restful API文档
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api