# 接口文档搭建（包括调试功能）

**Repository Path**: yolandahou/vuepress-api-doc

## Basic Information

- **Project Name**: 接口文档搭建（包括调试功能）
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-12-02
- **Last Updated**: 2021-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vuepress, Vue, Axios

## README

## 一、开发环境搭建

- [vscode](https://code.visualstudio.com/) IDE安装

  1.  打开项目后会提示安装推荐插件，请选择安装

- [nodejs](http://nodejs.cn/download/) Node安装

- yarn 安装

```
npm i -g yarn
```

## 二、快速开始

1. 拉取项目
```bash
git clone https://gitee.com/yolandahou/vuepress-api-doc.git
```

2. 安装依赖包

```bash
yarn install // 或者使用npm安装，安装命令为 npm install （推荐使用yarn）
```

3. 启动项目

```bash
# 使用测试环境启动
yarn dev （也可直接运行 package.json 中的 scripts 配置 dev）
# 使用生产环境启动
yarn dev:prod （也可直接运行 package.json 中的 scripts 配置 dev:prod）
```


4. 打包
```bash
# 测试环境打包
yarn build:test
# 生产环境打包
yarn build
```

## 三、相关文件

- [vuepress](https://vuepress.vuejs.org/zh/config/) Vue 驱动的静态网站生成器
- [vuepress-theme-vdoing](https://doc.xugaoyi.com/) VuePress 主题


## 四、目录结构描述

```
├── docs (必须，不要修改文件夹名称)
│   ├── .vuepress （同官方，https://vuepress.vuejs.org/zh/guide/directory-structure.html#目录结构）
│   ├── @pages (自动生成的文件夹，存放分类页、标签页、归档页)
│   ├── _posts (专门存放碎片化博客文章的文件夹)
│   ├── <结构化目录，存放文档目录>
│   └── index.md (首页)
├── utils  (node工具)
│   ├── modules
│   ├── config.yml (批量操作front matter配置)
│   └── editFrontmatter.js (批量操作front matter工具)
├── base.js (根目录设置)
├── deploy.sh (部署命令脚本)
├── Dockerfile (docker部署配置)
├── nginx.conf (nginx部署配置)
│
└── package.json
```


## 五、文档目录约定

> 文档存放在 docs-> 结构化目录

- 侧边栏：文件夹或文件 前面的 `数字.` 代表排序，侧边栏根据结构化目录中的结构自动生成，一个一级目录代表一个侧边栏。eg：`01.文档中心`为一级目录，连同它的子目录会生成一个侧边栏。
- 导航栏：`nav.test.js` 维护测试环境的导航栏；`nav.prod.js` 维护生产环境的导航栏。

- 文件夹、文件 [命名约定](https://doc.xugaoyi.com/apidocs/33d574/#%E5%91%BD%E5%90%8D%E7%BA%A6%E5%AE%9A)

> 接口调试工具
- 在.md文档中调用组件 `<debug/>` 
- 参数说明

| 字段            |  说明            |
|-----------------|------|
| title          | 必填，string类型，接口标题 |              
| link            | 必填，string类型，接口对应的说明文档链接 |           
| methodType    | 必填，string类型，'get' 或者 'post'，接口类型 |    
| url | 必填，string类型，接口地址。不包含接口前缀，以“/”开头 | 
| isToken | 必填，boolean类型，是否需要accessToken请求头 |  
| body | 选填，Object 或 Array类型，body类型请求参数 |  
| param | 选填，string类型，拼接在url的请求参数 | 
| queryParams | 选填，Object类型，query string Parameters参数，即：问号拼接在url的请求参数 |    

举例：

```ts
// 拼接在url的请求参数
<debug 
  title="根据id删除职位"
  link="/apidocs/635dc0/"
  methodType="post"
  url="/v1/position/delete/"
  :isToken=true
  :param="'1455072487191613441'"
/>

// body请求参数
<debug 
  title="根据id删除职位"
  link="/apidocs/635dc0/"
  methodType="post"
  url="/v1/position/delete/"
  :isToken=true
  :body='{"corpid":"k1455826074142257473","corpsecret":"06c8bdab4f564b831366adff2b673c61"}'
/>

// 问号拼接在url的请求参数
<debug 
  title="根据id删除职位"
  link="/apidocs/635dc0/"
  methodType="post"
  url="/v1/position/delete/"
  :isToken=true
  :queryParams='{"corpid":"k1455826074142257473","corpsecret":"06c8bdab4f564b831366adff2b673c61"}'
/>

```

## 六、子域名配置

访问地址如果有子域名，需要在根目录`base.js`文件中修改，使用图片时也要加上。

## 七、图片

图片存在 `docs->.vuepress->public->img`中，可根据需要建图片目录，使用时地址为`/子域名/img/图片子目录/xxx.png`

## 八、首页

`docs->index.md` 为首页，可以使用vuepress官方给出的默认首页，通过 frontmatter 配置，也可以自定义，使用 `layout`指定使用的自定义组件。自定义组件的目录放在`docs->.vuepress->components`

## 九、主题色修改

`docs->.vuepress->styles->palette.styl` 中修改 `$accentColor`

## 十、Markdown 语法

- [Markdown基础语法](http://markdown.p2hp.com/basic-syntax/)

- [Markdown语法扩展](https://doc.xugaoyi.com/pages/d0d7eb/)