一、概述

原文地址:https://pro.ant.design/docs/api-doc-cn

在日常开发中,往往是前后端分离的,这个时候约定好一套接口标准,前后端各自独立开发,就不会被对方的技术难点给阻塞住,从而保证项目进度。

在 Ant Design Pro 中我们已经有了一套比较完善的 mock 功能,而 roadhog-api-doc 工具,则能够从项目的 mock 数据中读取接口信息生成对应的文档,这样就能够更加清晰明了的展现项目的接口情况。

效果如下:Pro API Docs

二、详细

2.1、如何使用

npm install roadhog-api-doc -g

2,1.1、本地服务

进入到项目根目录,运行:

roadhog-api-doc start [port]

就可以在当前项目跑起一个文档网站,但是前提是必须跟 Ant Design Pro 一样是基于 roadhog 的项目,并且使用了数据 mock 功能,因为文档的信息来源就是 mock 文件。

需要额外注意的是,上面的 port 参数指的是当前本地的 roadhog 应用起的服务,如果指定了可以在本地直接点击访问项目接口,没有指定则会静态化网络请求。

访问:localhost:8001/api.html

2.1.2、静态站点生成

项目根目录,运行:

roadhog-api-doc build

会生成三个文档站点静态文件:api.htmlapi.jsapi.css,你可以将其部署到自己的站点中供线上访问,这里的数据已经被静态化(转换网络请求为代码数据)。

2.1.3、书写文档

通常来讲,你无需额外加入任何依赖就可以生成文档,但是如果你需要对接口做出说明,需要按照以下格式对 roadhog mock 文件进行修改:

npm install roadhog-api-doc --save-dev # 将 roadhog-api-doc 作为本地工具依赖安装
import { format } from 'roadhog-api-doc';

const proxy = {
'GET /api/currentUser': {
$desc: "获取当前用户接口",
$params: {
pageSize: {
desc: '分页',
exp: 2,
},
},
$body: {
name: 'momo.zxy',
avatar: imgMap.user,
userid: '00000001',
notifyCount: 12,
},
},
}; export default format(proxy);

其中:

  • $desc: 接口说明

  • $params: 接口参数说明,对象描述各个参数的意义

  • $body: 数据返回结果,通常就是 mock 的数据

2.1.4、本地测试 mock 数据和真实端口

当启动本地的 API Docs 站点以后,可以点击 send 按钮发送 POST 或者 GET 请求,并且返回值会在弹出框中显示:

其中需要注意的是,如果启动 API Docs 站点时,没有加端口号,那么这里的返回数据是静态数据,如果加了端口号并且本地也同时跑起了项目,那么就会直接返回实际数据。

如果你想直接访问线上的真实数据,那么需要改写当前项目的 .roadhog.mock.js重定向到线上路径。

可以通过访问 roadhog-api-doc github 了解更多。

ant design pro (十五)advanced 使用 API 文档工具的更多相关文章

  1. Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

    1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...

  2. 通过Dapr实现一个简单的基于.net的微服务电商系统(十五)——集中式接口文档实现

    之前有小伙伴在评论区留言说如何集成swagger,最开始没有想透给了对方一个似是而非的回答.实际上后来下来想了一下,用.NET5 提供的Source Generator其实可以很方便的实现接口集成.今 ...

  3. API文档工具-Swagger的集成

    最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...

  4. 开源的API文档工具框架——Swagger简介

    初次接触Swagger是在2017年5月,当时公司正好要对整套系统架构进行重新设计,有同事推荐用这个技术框架来规范后台接口的API文档.当时因为架构重构,涉及改造的技术点太多,一时也就没太多精力,把S ...

  5. 开源API文档工具- swagger2 与 smart-doc 比较 与 使用

    工具开源地址 swagger2 : https://swagger.io/ smart-doc: https://www.oschina.net/p/smart-doc  国产 两者的比较 swagg ...

  6. ant design pro (五)新增业务组件

    一.概述 参看地址:https://pro.ant.design/docs/new-component-cn 对于一些可能被多处引用的功能模块,建议提炼成业务组件统一管理.这些组件一般有以下特征: 只 ...

  7. api文档工具

    平台选型         Apidoc         文档参考:http://apidocjs.com        优点      文档齐全,操作简单,ui清晰,代码注解查询性强,语言支持多元化, ...

  8. Net Core的API文档工具Swagger

    一.安装swagger 新建一个net core的api项目,通过NuGet安装Swashbuckle.AspNetCore. 二.注册swagger服务 在Startup.cs中注册Swagger生 ...

  9. Ant Design Pro (中后台系统)教程

    一.概念:https://pro.ant.design/docs/getting-started-cn(官方网站) 1.Ant Design Pro 是什么:  https://www.cnblogs ...

随机推荐

  1. Codeforces 521 E cycling city

    cf的一道题,非常有意思,题目是问图中是否存在两个点,使得这两个点之间有三条路径,而且三条路径没有公共点. 其实就是判断一下是否为仙人掌就行了,如果不是仙人掌的话肯定就存在,题目难在输出路径上,改了半 ...

  2. 【尺取法好题】POJ2566-Bound Found

    [题目大意] 给出一个整数列,求一段子序列之和最接近所给出的t.输出该段子序列之和及左右端点. [思路] ……前缀和比较神奇的想法.一般来说,我们必须要保证数列单调性,才能使用尺取法. 预处理出前i个 ...

  3. Varnish与Squid的对比

    Varnish与Squid的对比 说到Varnish,就不能不提Squid.Squid是一个高性能的代理缓存服务器,它和Varnish相比较有诸多的异同点,下面进行分析. 下面是Varnish与Squ ...

  4. MySQL遇到的一个卡库问题及对update的学习

    近日遇到个卡库的问题,环境是MySQL5.5.12,报错信息如下 ) and was aborted. There is a chan ce that your master is inconsist ...

  5. Vue学习记录-状态管理

    要解决的问题 平时的系统开发中,基本都会碰到这个权限问题,需要根据用户的登录状态进行处理.最常见的情况就是“先登录,后使用”.除去打包成APP,无法看到连接外,如果地址栏里直接输入地址就能绕过登录的话 ...

  6. UVA 11205 The broken pedometer(子集枚举)

    B - The broken pedometer Time Limit:3000MS     Memory Limit:0KB     64bit IO Format:%lld & %llu ...

  7. iOS可持续化集成: Jenkins + bundler + cocoapods + shenzhen + fastlane + pgyer

    工具介绍 1. bundler bundler用于管理ruby gem的工具,我们用来管理cocoapods以及fastlane的版本.直接sudo gem install bundler就可以.然后 ...

  8. Can a windows dll retrieve its own filename?

    http://stackoverflow.com/questions/2043/can-a-windows-dll-retrieve-its-own-filename A windows exe fi ...

  9. 阻止picker.js插件弹出键盘

    <input id="focus" type="text" value="" placeholder="手机号" ...

  10. 关于禁用html中a标签的思考

    事实上这个问题在初次学习html中select标签时就已经冒出来了,时至今日,依旧没有找到使用纯css禁用a标签的办法--同事.同学.老师我都问过了,他们都千篇一律借助了JavaScript,难道真的 ...