【硬核教程】只需1秒—你也可以有自己的API文件

SH的全棧筆記發表於2019-12-27

Nothing is true. Everything is permitted.

寫在前面

先聊聊為什麼想到了要用Vuepress來代替原來寫在Confluence上的文件。

大意是有個需要其他部門接入的專案,這個專案有個用md寫的接入文件,其他部門的人需要看著這個文件才知道怎麼接以及哪些東西需要接。

但是有個問題是這個文件長的一匹,有多長呢?

而且這個md檔案是放在confluence上的。

本身用confluence閱讀md的體驗就不好,這個文件能夠讓你的滾輪滾個足足十多秒,skr~。

你想要看的某個小章節就藏在這一大坨文字裡。即使從最上面的導航錨點定位到了想要看的地方,但是你看著看著,滑著滑著就不知道自己在哪兒了。

然後找了半天,要麼你運氣好找到了。要麼就只有回到最上面的導航,在一堆導航裡再找一次。如果你運氣究極不好,可能還要把上面的步驟重複幾次,真的到了那個時候,你的心態可能就炸了。還接個毛的業務,心裡只想找到寫文件的人,然後一頓操作。

這就是為什麼,我想換個方式來展示這個介面文件

說到這個,又不得不吐槽。去網上找了很多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 = {
    smoothScrolltrue,
    title'需要你在config.js裡單獨配的標題',
    themeConfig: {
        sidebar: router.getSidebar()
    },
    plugins: ['vuepress-plugin-smooth-scroll'],
};
複製程式碼

我這裡只用了一個外掛,但是我展示出了用外掛的正確姿勢,vuepress有很多外掛,如果需要可以自己按需安裝。

你可能看到了,最終的sidebar是通過一個函式生成的。

router.js在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的張三',
        ]
    }
]
複製程式碼

然後就可以在詳情多看到一些頁面了。

值得注意的是,groupA和groupB的目錄下的README檔案就是你點選類別A這個分組顯示的預設頁面。

在vuepress中,如果路由以/結尾,那麼就是指的這個目錄下的README.md檔案

還有一點很方便的是,單個檔案裡如果你有二級標題,vuepress會自動的生成該檔案下的二級標題導航。點選相應的二級標題還可以直接跳轉到對應的錨點,如下圖。

自動生成錨點
自動生成錨點

如果你還需要更多功能

如果你作為一個後端開發, 要想展示你的文件,其實我認為完全夠了。

不過你還需要更多功能的話,建議還是直接去vuepress官網檢視對應的文件。

如果你覺得這篇文章對你有幫助,還麻煩點個贊關個注分個享留個言

也可以微信搜尋公眾號【SH的全棧筆記】,當然也可以直接掃描二維碼關注

拜了個拜

【硬核教程】只需1秒—你也可以有自己的API文件

相關文章