springboot 第十七节 springboot集成apidoc

本文详细介绍如何使用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,可以看到文档页面:

 

 

 

更多配置:http://apidocjs.com/#configuration

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值