有关api定义和文档书写的问题

API文档

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

API格式

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

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

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

API文档生成工具

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

fhawk 1楼•6 年前

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

ProfutW 2楼•6 年前作者

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

来自酷炫的 CNodeMD

im-here 3楼•6 年前

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

dingyuanwu 4楼•6 年前

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

ProfutW 5楼•6 年前作者

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

nullcc 6楼•6 年前

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

ProfutW 7楼•6 年前作者

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

来自酷炫的 CNodeMD

fhawk 8楼•6 年前

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

ProfutW 9楼•6 年前作者

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