springboot 第十七节 springboot集成apidoc

最新推荐文章于 2024-06-24 14:48:13 发布

原创最新推荐文章于 2024-06-24 14:48:13 发布 · 264 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#springboot

spring boot 专栏收录该内容

38 篇文章

订阅专栏

本文详细介绍如何使用apidoc工具自动生成SpringBoot项目的API文档，包括安装node.js、apidoc，以及在Controller层中如何正确标注请求路径和参数，最后通过生成的apidoc.json文件在指定目录下输出文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、参考文章

https://blog.youkuaiyun.com/forezp/article/details/71023579

1、安装node.js

2、安装api.doc,它的项目源码：https://github.com/apidoc/apidoc 。

npm install apidoc -g

3、controller层请求路径写法


import org.springframework.web.bind.annotation.*;

/**
 * 先安装node.js
 * 在安装apidoc
 * Created by fangzhipeng on 2017/4/17.
 */
@RestController
@RequestMapping(value = "/user")
public class UserController {

    /**
     * @api {get} /user/:id  获取用户信息
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */
    @RequestMapping (value = "/{id}",method = RequestMethod.GET)
    public String getUser(@PathVariable(name = "id")long  id){
            return "用户id为"+id;
    }


    /**
     * @api {POST} /login 用户登录
     * @apiGroup Users
     * @apiVersion 0.0.1
     * @apiDescription 用于用户登录
     * @apiParam {String} userName 用户名
     * @apiParam {String} password 密码
     * @apiParamExample {json} 请求样例：
     *                ?userName=张三&password=11223344
     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
     * @apiSuccess (200) {String} user 用户信息
     * @apiSuccess (200) {String} userId 用户id
     * @apiSuccessExample {json} 返回样例:
     *                {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
     */



    /**
     * @api {POST} /users/:id 修改(完善)用户信息
     * @apiGroup Users
     * @apiVersion 0.0.1
     * @apiDescription 修改(完善)用户信息
     * @apiParam (200) {String} [name] 真实姓名
     * @apiParam (200) {String} [mobile] 手机号
     * @apiParam (200) {String} [birthday] 生日
     * @apiParam (200) {String} [email] 邮箱
     * @apiParam (200) {String} [summary] 简介
     * @apiParam (200) {String} [idCardNo] 身份证号
     * @apiParam (200) {String} [address] 家庭住址
     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     * @apiSuccessExample {json} 返回样例:
     *                {"code":"0","msg":"修改成功"}
     */
}

主要字段就是：

@api {method} path [title] method：请求方法， path：请求路径 title(可选)：标题

步骤1：

在项目的主目录新建一个apidoc.json文件：

步骤2:

先cd到工程的外层目录，并在外层目建个输出文档的目录，我建的是docapi。

apidoc -i springboot-apidoc/ -o apidoc/

步驟3：

打开index.html,可以看到文档页面: