【硬核教程】只需1秒—你也能夠有本身的API文檔

時間 2020-01-04

標籤硬核教程只需 1秒能夠本身 api 文檔简体版

原文原文鏈接

Nothing is true. Everything is permitted.

寫在前面

先聊聊爲何想到了要用Vuepress來代替原來寫在Confluence上的文檔。javascript

大意是有個須要其餘部門接入的項目，這個項目有個用md寫的接入文檔，其餘部門的人須要看着這個文檔才知道怎麼接以及哪些東西須要接。vue

可是有個問題是這個文檔長的一匹，有多長呢？java

並且這個md文件是放在confluence上的。git

自己用confluence閱讀md的體驗就很差，這個文檔可以讓你的滾輪滾個足足十多秒，skr~。github

你想要看的某個小章節就藏在這一大坨文字裏。即便從最上面的導航錨點定位到了想要看的地方，可是你看着看着，滑着滑着就不知道本身在哪兒了。npm

而後找了半天，要麼你運氣好找到了。要麼就只有回到最上面的導航，在一堆導航裏再找一次。若是你運氣究極很差，可能還要把上面的步驟重複幾回，真的到了那個時候，你的心態可能就炸了。還接個毛的業務，內心只想找到寫文檔的人，而後一頓操做。json

這就是爲何，我想換個方式來展現這個接口文檔。後端

說到這個，又不得不吐槽。去網上找了不少vuepress的使用，整體下來兩個字，複雜。再去看看vuepress的官方文檔（雖然最後的解決方案都是在官方找到的），總結下來也是兩個字，懵逼（由於我想找的那個地方藏得比較深）。數組

因而就有了寫這一期硬核教程。瀏覽器

Don't BB, 你這個項目啓起來到底啥樣？

我看的不少教程，都是在沒有背景、沒有代碼、沒有效果的狀況就開始了。讓原本但願經過這個教程入門的人懵上加懵（好比我）。

Github地址： -> 戳此 <-
*牆裂建議，先拉下來看看效果。*

直接npm install安裝完依賴以後，直接npm start便可。在你本地的8080端口就會運行一個以下的界面。

並非自動打開瀏覽器，須要手動進入本地項目地址

而後點開始開發會進入到以下的詳細界面。

左邊就是咱們須要詳細展現的文檔，能夠看到我簡單的分了兩類做爲樣例。

好了好了，效果看到了，Show me the code

首先，這個項目的目錄長這樣。

.
├── .vuepress
│   ├── config.js
│   ├── public
│   │   └── logo.jpg
│   └── router.js
├── LICENSE
├── README.md
├── groupA
│   ├── README.md
│   └── 類別A的李四.md
├── groupB
│   ├── README.md
│   └── 類別B的張三.md
├── package-lock.json
└── package.json

接下來就分別將一下首頁和詳情頁是怎麼來的，以及若是須要加一個頁面（也就是路由）該怎麼作。

首先是首頁

項目的根目錄下的README.md就是你剛剛看到的首頁。裏面的源碼長這樣，你能夠對比首頁來看。

---
home: true
heroImage: /logo.jpg
heroText: 你的標題
tagline: 你的副標題
lang: en-US
actionText: 開始開發 →
actionLink: /groupA/
features:
- title: 吹🐂🍺
  details: 這是吹🐂🍺的詳情
- title: 繼續吹🐂🍺
  details: 這是繼續吹🐂🍺的詳情
- title: 再繼續吹🐂🍺
  details: 這是再繼續吹🐂🍺的詳情
footer: MIT Licensed | Copyright © 2019-present LunhaoHu
---

配成上面這樣，你就能夠看到剛剛那個首頁。

沒錯，不用你去寫任何的JavaScript和CSS，所有都是基於配置的。

順嘴一提，只要你把圖片放在了 .vuepress的public目錄下，那麼寫圖片src的時候能夠直接 /你的圖片名便可。

而後是詳情頁

能夠看到，在首頁的配置中，有一個actionLink，這個是指點了首頁中的開始開發，須要跳轉到的路由。這個就是咱們衆多詳情中的其中一個頁面的路由。

你能夠對比剛剛詳情頁的圖片。咱們之因此可以看到左邊的側邊欄，是由於在config.js裏配置了sidebar這個屬性。以下。

const router = require('./router');

module.exports = {
    smoothScroll: true,
    title: '須要你在config.js裏單獨配的標題',
    themeConfig: {
        sidebar: router.getSidebar()
    },
    plugins: ['vuepress-plugin-smooth-scroll'],
};

我這裏只用了一個插件，可是我展現出了用插件的正確姿式，vuepress有不少插件，若是須要能夠本身按需安裝。

let data = [
    {
        'title': '類別A',
        'path': '/groupA/',
        'children': [
            '類別A的李四',
        ]
    },
    {
        'title': '類別B',
        'path': '/groupB/',
        'children': [
            '類別B的張三',
        ]
    }
];

/**
 * 生成sidebar數據
 *
 * @param data 上面定義的抽象側邊欄路由靜態文件
 */
exports.getSidebar = () => {
    let sidebar = [];
    data.forEach((item) => {
        if (item.children.length === 0) {
            sidebar.push(item);
            return;
        }

        for (let i = 0; i < item.children.length; i++) {
            let childrenPath = item.children[i];
            item.children[i] = item.path + childrenPath;
        }
        sidebar.push(item);
    });
    return sidebar;
};

getSidebar這個函數，大意就是給全部的children加上了一個前綴path。由於vuepress自己須要你配置成這樣。例如，若是你直接使用的話，路由就會變成這樣。

注意，如下不是正確打開方式

[
  {
    title: '類別A',
    path: '/groupA/',
    children: [
      '/groupA/類別A的李四'
    ]
  },
  {
    title: '類別B',
    path: '/groupB/',
    children: [
      '/groupB/類別B的張三',
    ]
  }
]

在children中再加前綴，顯得很沒有必要。因此我簡單的作了一層抽象。

那麼若是你要加一個頁面要怎麼作呢？

舉個例子，加入你要在項目目錄groupA中新建一個叫類別A的王五.md的md文件，那麼你只須要在對應的router中，找到groupA這個類別，而後在children數組中再加一個類別A的王五便可。以下。

正確打開方式

[
    {
        'title': '類別A',
        'path': '/groupA/',
        'children': [
            '類別A的李四',
            '類別A的王五'
        ]
    },
    {
        'title': '類別B',
        'path': '/groupB/',
        'children': [
            '類別B的張三',
        ]
    }
]

而後就能夠在詳情多看到一些頁面了。