使用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