使用apidoc生成文档

apidoc是通过在方法上的注释生成文档，不基于任何框架，对代码没有侵入性，只需要写好相关的注释即可，并且它仅通过写简单的配置就可以生成高颜值的api接口页面。

准备工作

apidoc基于node.js,需要先行安装node.js，nodejs官网:node.js

安装apidoc

npm install apidoc -g

文档注释

官网详细参考： apidoc 示例，下面罗列出常用注解

@api {method} path {title}

method:请求方法（get/post/put/delete/....)
path:请求路径
title:标题（可选）

@apiDescription text

text:说明

@apiGroup name

name:组名

@apiParam {type} name text

type: 参数类型
name：参数名称
text: 参数说明

示例

首先写配置文件

在项目的根路径下新建一个apidoc.json文件

{"name": "基于RESTful风格API文档","version": "1.0.0","description": "图书apiDoc示例"
}

更多配置参考官网:http://apidocjs.com/#configuration

方法上注释

package edu.uestc.avatar.controller;import edu.uestc.avatar.domain.Book;
import edu.uestc.avatar.service.BookService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.List;@RestController
public class BookRestController {@Autowired private BookService service;/*** @api {post} /book 保存图书信息* @apiGroup Book* @apiParam {json} book 图书信息json格式* @apiParamExample {json} 参数格式:* {*     "title": "spring boot基础",*     "author": "tiger",*     "sellPrice": 38.0,*     "marketPrice": 80.0,*     "buyPrice": 10.0,*     "coverPath": "http://img.avatar.com:8080/files/images/连城诀.jpg",*     "publisher": "UESTC",*     "publishedDate": "2010-10-20"* }* @apiVersion 1.0.0** @apiSuccessExample {json} 主键回填后的图书信息:* {*         "id": 13,*         "title": "书剑恩仇录",*         "author": "金庸",*         "sellPrice": 88.0,*         "marketPrice": 200.0,*         "buyPrice": 18.0,*         "coverPath": "http://img.avatar.com:8080/files/images/书剑恩仇录.jpg",*         "publishedDate": "2022-05-02",*         "publisher": "三联出版社",*         "intro": "",*         "savedPrice": 112.0*     }*/@PostMapping("/book")public Book save(@RequestBody Book book){return service.save(book);}/*** @api {delete} /book/:id 删除图书* @apiDescription 根据图书id删除图书信息* @apiParam {int} id 图书唯一编号* @apiGroup Book* @apiVersion 1.0.0* @apiSuccessExample {json} 删除前的图书信息* {*     "id": 13,*     "title": "书剑恩仇录",*     "author": "金庸",*     "sellPrice": 88.0,*     "marketPrice": 200.0,*     "buyPrice": 18.0,*     "coverPath": "http://img.avatar.com:8080/files/images/书剑恩仇录.jpg",*     "publishedDate": "2022-05-02",*     "publisher": "三联出版社",*      "intro": "",*      "savedPrice": 112.0*  }**/@DeleteMapping("/book/{id}")public Book removeById(@PathVariable Integer id){return service.removeById(id);}/*** @api {put} /book 修改图书信息* @apiGroup Book* @apiParam {json} book 图书信息json格式* @apiParamExample {json} 参数格式，需要指定图书id:* {*     "id": 10,*     "title": "spring boot基础",*     "author": "tiger",*     "sellPrice": 38.0,*     "marketPrice": 80.0,*     "buyPrice": 10.0,*     "coverPath": "http://img.avatar.com:8080/files/images/连城诀.jpg",*     "publisher": "UESTC",*     "publishedDate": "2010-10-20"* }* @apiVersion 1.0.0** @apiSuccessExample {json} 修改前的图书信息:* {*         "id": 10,*         "title": "书剑恩仇录",*         "author": "金庸",*         "sellPrice": 88.0,*         "marketPrice": 200.0,*         "buyPrice": 18.0,*         "coverPath": "http://img.avatar.com:8080/files/images/书剑恩仇录.jpg",*         "publishedDate": "2022-05-02",*         "publisher": "三联出版社",*         "intro": "",*         "savedPrice": 112.0*     }*/@PutMapping("/book")public Book edit(@RequestBody Book book){return service.update(book);}/*** @api {get} /book/:id 根据图书编号加载图书信息* @apiGroup Book* @apiParam {int} id 图书编号* @apiVersion 1.0.0** @apiSuccessExample {json} 加载到的图书信息:* {*         "id": 10,*         "title": "书剑恩仇录",*         "author": "金庸",*         "sellPrice": 88.0,*         "marketPrice": 200.0,*         "buyPrice": 18.0,*         "coverPath": "http://img.avatar.com:8080/files/images/书剑恩仇录.jpg",*         "publishedDate": "2022-05-02",*         "publisher": "三联出版社",*         "intro": "",*         "savedPrice": 112.0*     }*/@GetMapping("/book/{id}") public Book findById(@PathVariable Integer id){return service.findById(id);}/*** @api {get} /book 加载所有图书信息* @apiGroup Book* @apiVersion 1.0.0** @apiSuccessExample {json} 加载到的图书信息:* [{*         "id": 10,*         "title": "书剑恩仇录",*         "author": "金庸",*         "sellPrice": 88.0,*         "marketPrice": 200.0,*         "buyPrice": 18.0,*         "coverPath": "http://img.avatar.com:8080/files/images/书剑恩仇录.jpg",*         "publishedDate": "2022-05-02",*         "publisher": "三联出版社",*         "intro": "",*         "savedPrice": 112.0*     }]*/@GetMapping("/book") public List<Book> list(){return service.list();}
}

用apidoc命令生成文档

apidoc -i 项目路径 -o 输出路径

到输出路径下，可以看到生成了文档文件，打开index.html

使用apidoc生成文档相关推荐

apidoc生成文档时报错
问题描述在书写完接口的时候,使用apidoc来生成我们所需要的接口文档的时候,输入apidoc.cmd -i ./constroller -o ./doc ,其中constroller 指定读取源文 ...
使用 apiDoc 为你的Node.js API 生成文档
翻译: 疯狂的技术宅原文:jonathas.com/documenting- 未经许可,禁止转载! 当你为其他开发人员(前端,桌面,移动等)开发 API 时,需要生成一份风格良好的文档,以便他们知道 ...
Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
Objective-C 自动生成文档工具:appledoc
来源:iOS_小松哥 www.jianshu.com/p/fd4d8d6b6177 如有好文章投稿,请点击 → 这里了解详情由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective ...
java前端目录_[Java教程]前端那点事儿——Tocify自动生成文档目录
[Java教程]前端那点事儿--Tocify自动生成文档目录 0 2016-06-29 22:00:07 今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目 ...
快速优雅的为React组件生成文档
在开发React组件时我们通常需要处理2个问题: 实例化这个组件以便调试为这个组件编写使用文档以便更好的让别人知道怎么使用这个组件最原始的方法莫过于开发时建一个页面用于调试,开发完后再为其手写文档 ...
linux c/c++ 代码使用 doxygen 自动生成文档
www.doxygen.org 的使用非常方便,下面分成2步介绍一下 1. 注释风格,需要在c/c++代码中按照下面的风格添加注释,基本上还是很顺手的 C++的注释风格主要使用下面这种样式:即在注释 ...
使用DocFX生成文档
使用DocFX命令行生成文档使用docfx 命令 1.下载 https://github.com/dotnet/docfx/releases 2.使用创建初始项目 docfx init -q 此命 ...
docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档
为什么用 TypeScript? TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any ...