开发者社区> imzdx> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

使用apidoc 生成Restful web Api文档——新手问题与解决方法

简介: 使用apidoc工具来给项目做接口文档,不仅有合理的源码注释,还可以生成对应的文档。是给源码写备注的一个极佳实践。 工具名称:apiDoc Git地址:https://github.com/apidoc/apidoc 项目地址:http://apidocjs.
+关注继续查看

使用apidoc工具来给项目做接口文档,不仅有合理的源码注释,还可以生成对应的文档。是给源码写备注的一个极佳实践。


工具名称:apiDoc 
Git地址:https://github.com/apidoc/apidoc 
项目地址:http://apidocjs.com/ 
样例项目:http://apidocjs.com/example_basic/ 

博客学习:http://blog.csdn.net/soslinken/article/details/50468896

出现的问题:
 

1. 运行:apidoc -i test/ -o apidoc/,

 问题:提示 warn: Please create an apidoc.json configuration file.

 解决:在项目源码文件夹创建 apidoc.json 文件

{
  "name": "测试",
  "version": "0.0.1",
  "description": "API文档测试",
  "title": "API文档测试",
  "url" : "http://xxxxxxx",
  "sampleUrl" : "http://xxxxxxxx",
  "template":{
    "forceLanguage":"zh-cn"
  }
}

 

2. 运行:apidoc -i test/ -o apidoc/,

 问题:提示如下错误

Block: 2,
Element: '@apiParam',
Source: '@apiParam {Number} 当前分页.'


Block: 3,
Element: '@apiSuccess',
Source: '@apiSuccess {String} 新增博文页面.'

 说明:@apiParam、@apiSuccess 等注解后面需要加上结果

    使用规范:@apiSuccess [(group)] [{type}] field [description]

 解决:在文字前面加上与 field “返回字段的名称” 对应的结果,没有结果时写 null 即可。

 

3. 运行:apidoc -i test/ -o apidoc/ 没有报错,得到结果

 问题:打开的界面只有loading,没有显示内容

 说明:在查找很多相关内容之后,有可能的结果是说配置文件中的version需要和apidoc对应,结果删除了也不行。后面把配置文件修改成最初状态,正常导出API文档。

 解决:将apidoc.json文件修改成如上的默认状态,重新生成即可完成

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
Spring Boot 2.X(三):使用 Spring MVC + MyBatis + Thymeleaf 开发 web 应用
前言 Spring MVC 是构建在 Servlet API 上的原生框架,并从一开始就包含在 Spring 框架中。本文主要通过简述 Spring MVC 的架构及分析,并用 Spring Boot + Spring MVC + MyBatis (SSM)+ Thymeleaf(模板引擎) 框架来简单快速构建一个 Web 项目。
1103 0
python web service开发
记录第一个web python服务
9592 0
从 React 谈 Web UI 开发
此前我在 Twitter 上这样表达过对 React 的理解,但是 Twitter 篇幅有限,所以在这篇文章里,我要做更详尽的阐述。
491 0
Spring Boot 《一》开发一个“HelloWorld”的 web 应用
Spring Boot 《一》开发一个“HelloWorld”的 web 应用
1091 0
Flutter for Web开发环境安装【1.5.4】
最新的Flutter 1.5.4已经支持Web开发,这个教程将介绍如何在Linux、windows和Mac下安装Flutter web开发环境:安装Flutter SDK和Flutter Web构建工具,并利用Flutter Web演示代码来验证开发环境搭建成功。
2777 0
好程序员web开发分享CSS3新增属性
好程序员web开发分享CSS3新增属性CSS3 背景的新增属性 1、Background-origin 背景原点说明:指定background-origin属性应该是相对位置属性值:padding-box 背景图像填充框的相对位置 border-box 背景图像边界框的相对位置 content-box 背景图像的相对位置的内容框 注:默认值为:padding-box;2、Background-clip 背景裁切说明:background-clip 属性规定背景的绘制区域。
813 0
java开发之使用websocket实现web客户端与服务器之间的实时通讯
使用websocket实现web客户端与服务器之间的实时通讯。以下是个简单的demo。
8760 0
使用Sanic开发快速异步响应的Web程序
Sanic是一个类似Flask、仅仅支持Python 3.5+ 版本的web 服务器,旨在运行速度更快。在类似Flask的基础上,Sanic支持异步请求处理,也就是说,你可以使用Python 3.5 中全新而又亮眼的 async/await 语法,使你的代码非阻塞且快速。
1717 0
自开发Web应用和SAP Customer Data Cloud Identity服务的集成
今天的文章继续由SAP成都研究院的云时代女王,Aviva给大家分享关于SAP Customer Data Cloud的一些使用经验。 Aviva之前的文章可以在本文末尾处获得。 下面是她的正文。 * 大家好,我是Aviva。
1125 0
SpringBoot实现Java高并发秒杀系统之Web层开发(三)
SpringBoot实现Java高并发秒杀系统之Web层开发(三) 接着上一篇文章:SpringBoot实现Java高并发之Service层开发,今天我们开始讲SpringBoot实现Java高并发秒杀系统之Web层开发。
5808 0
+关注
imzdx
数据库相关技术专家
322
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
低代码开发师(初级)实战教程
立即下载
阿里巴巴DevOps 最佳实践手册
立即下载
冬季实战营第三期:MySQL数据库进阶实战
立即下载