有关api定义和文档书写的问题
发布于 8 个月前 作者 ProfutW 941 次浏览 来自 问答

API文档

我理解的一般的web项目中API返回信息应该有两种,一种是JSON(对于ajax请求),另一种是渲染好的HTML页面(比如form表单请求); 那么书写API文档的时候,对于后台直接返回页面的API大家一般是怎么写响应信息的?

API格式

在一个项目中前后端交互的API如果返回是JSON的话,格式一般都是固定的,比如下面这样:

    {
		"status": {
			"code": 0,
			"msg": "success"
		},
		"data": {}
	}

那么默认情况下,每次响应成功应该只有data不同(除非需要根据响应内容不同自定义响应状态),这样的情况下文档中应该不需要每次都标注status的内容吧?否则文档中冗余的内容也太多了吧

API文档生成工具

大家一般用什么工具来写API文档?我搜索了一下好像apidoc推荐的比较多,有什么别的建议吗?

9 回复

一般api请求返回的数据有两种格式,一种是JSON,另一种却不是html页面,而是xml文本。 所以最好在文档里写一个返回数据的范例,并注明返回数据的说明。

@fhawk 你说的应该是纯API服务 就是只提供数据接口的那种 我的意思是一般web项目中前端发出请求 后端不应该要返回页面吗 这种API怎么写?

来自酷炫的 CNodeMD

你说的不写status内容也是可行的,只需在某一个地方写标注说明一些status的内容就行了 ,只要规范就行 至于工具我的话我推荐 slate apidoc也是可以的

apidoc,在node这边就目前使用的情况来看,还可以

@im-here @dingyuanwu 谢谢 第一个问题怎么看?还是说像这种直接返回页面的API不需要写响应内容 只需要写请求参数?

当然是用酷炫的swagger了,试过多种API文档类的东西,最后还是用swagger,目前市面上开源的API文档工具,swagger应该最实用的

@nullcc 多谢 明天来看看 第一个问题能帮忙解决一下吗?

来自酷炫的 CNodeMD

@ProfutW 建议你看看vue或者reat,完全可以做到前后端分离。

@fhawk 谢谢 不过我不是问前后端分离怎么做。。。我认为前后端分离的项目适合以前的旧系统或者大型项目 一般的项目做前后端分离只会额外增加请求的次数和响应时间,因为需要中间层(一般就是node来做)请求后端数据接口。至于你说的vue或者react,其实并不算是前后端分离,我觉得只是前端工程化,因为真正的前后端分离后端是只提供数据接口的,渲染视图应该交由中间层来实现(只是我个人的看法,说的不对的请大家指出。。)我想问的其实很简单,就是在没有中间层这个概念下,我后端就是node,它既提供数据接口(与数据库交互),也用来渲染页面(我觉得一般的项目应该都是这样吧),这样的情况下,API应该如何定义,文档应该怎么写比较合理。

回到顶部