Panda Api纯文档编写和多级菜单目录文档

除了用json5编写接口文档,Panda Api还支持像微信公众号接口文档一样的纯文档编写, 例如 https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html 中的 开发前必读 的子菜单: 首页、更新日志、开发着规范、接口权限说明、全局返回码说明、入门指引 都是纯文档的,开始开发的子菜单:接入指南、接口域名说明、接口测试账号申请、报警排查指引也都是纯文档的。

微信公众号接口文档截图

这些文档都是纯文档的,不需要提供接口服务,也不需要进行测试,单纯的只是文档,这些文档和接口文档在一起,作为接口文档的一部分,进行更详细的说明。

Panda Api也支持这样的文档编写,使用Markdown语法,文档展示出来的时候,Panda Api会把markdown的内容渲染为html内容。

以下功能对markdown文档和json5文档都是适用的

支持多级菜单

可以使用文件夹支持多级菜单目录,文件夹目录会对应到菜单目录。像微信公众号开发文档的例子,我们可以这样建立目录和文件:

├── $1 开发前必读
│   ├── $1 首页.md
│   ├── $2 更新日志.md
│   ├── $3 开发者规范.md
│   ├── $4 接口权限说明.md
│   ├── $5 全局返回码说明.md
│   └── $6 入门指引.md
├── $2 开始开发
│   ├── $1 接入指南.md
│   ├── $2 接口域名说明.md
│   ├── $3 接口测试号申请.md
│   ├── $4 报警排查指引.md
│   └── $5 常见问题.md

多级菜单目录同样适用语言json5格式的接口文档,而且可以根据需要把json5文档和markdown文档混合放在同一级菜单中使用。

使用文件名控制菜单排序和名称

目录名和文件名的最开始有一个美元符号$加一个数字,这个表示菜单和文档在菜单上显示的排序,这个美元符号$和数字不会在菜单上展示出来。例如: $1 开发前必读,里面的1是排序,开发前必读是菜单名称。$1后面的空格是可选的。

api接口文档和markdown纯文档的顺序的统一的,也就是通过调整排序,使得纯markdown的文档可以穿插到api接口文档之间。

api接口文档和markdown接口文档都支持多级目录,多级目录会对应到前端的多级菜单上。

在文档中配置排序和名称

如果不想把排序order写在文件名上,或者文件名和显示的菜单名不一致,我们可以在对应md文件的内容头进行配置,例如我们把 想让更新日志在菜单上显示为:接口更新日志, 排序改为,可以在$2 更新日志.md内容的开头进行设置:

Panda Api纯文档设置截图

$2 更新日志.md的内容开头用三个反引号包裹,中间一个json5的配置,{menu_title: "接口更新日志",order:7}, menu_title表示在菜单上显示的名称,order表示排序,如果在文件内容中设置了order,那么就以文件内容中的为准。如果文件名开头和文件内容开头都没有设置,那么默认的排序order, 默认的menu_title就是文件名。

配置文件夹菜单

所有的文件夹菜单,作为一个父级菜单,默认情况下,仅只是一个菜单,只能点开查看下级菜单,是不能点开查看这个菜单对应的页面内容的。

我们还可以在要展示内容的文件夹中创建一个文件$_folder.md来配置 是否可以点开展示内容show_content,以及要展示的内容,同时还可以配置这个菜单的排序order,名称menu_title

例如我们想让开发前必读这个父级菜单,也可以点开展示内容,那么就在开发者必读这个文件夹中创建文件$_folder.md,内容如下:

\`\`\` // -> 这里是三个反引号,为了显示,所以加了三个反斜杆, 如果要复制使用,要去掉反斜杠
{
    menu_title: "6666",
    order:10,
    show_content:true
}
\`\`\` // -> 这里是三个反引号,为了显示,所以加了三个反斜杆, 如果要复制使用,要去掉反斜杠

# 这里是内容
# Hello World

配置后,开发前必读就变成了一个可以点开,并展示页面内容的菜单。点开展示的内容就是

<h1>这里是内容</h1>
<h1>Hello World</h1>

静态文件 图片或其它存放

markdown文档的时候,经常会用到一些图片,我们可以把图片放到接口文档根目录的media目录或者static目录,比如一张图片a.png放到media目录里面,这时的路径是:media/a.png,我们在markdown文档中使用这个图片要这么写:

![xxx](/media/a.png)

xxx 是图片标签,根据自己的需要设置即可。

2020-02-18 08:04

留言