Skip to main content

API Documentation Plugin

How to Use​

Berikut cara menggunakan plugin setelah dilakukan setup.

One Version​

Untuk API yang hanya memiliki 1 versi.

Delete Generated API​

npm run docusaurus clean-api-docs all

Generate The API Docs​

npm run docusaurus gen-api-docs all

More Than One Version​

Untuk API yang memiliki lebih dari 1 versi.

Delete Generated API​

Untuk menghapus hasil generate APi tipe version, dilakukan secara manual, yaitu langsung dihapus saja folder dan file terkait.

Generate The API Docs​

npm run docusaurus gen-api-docs:version regcourse:all

How to Develop​

Define The API Versions​

Pertama, definisikan file mana yang akan digenerate, namakan versi, dan tampilan seperti apa yang diinginkan

docusaurus.config.js
regcourse: {
// nama api
  specPath: "apis/reg-course.yaml",
  // alamat file yang akan di generate
  outputDir: "docs/api/reg-course-versioned",
  // alamat dimana file hasil generate disimpan
  sidebarOptions: {
    groupPathsBy: "tag",
    categoryLinkSource: "tag",
  },

  // Dibawah ini adalah bagian yang ditambahkan jika ingin membuat API yang memiliki beberapa Versi

  version: "2.0",
  // Mendefinisikan the latest API yang dijadikan API utama // Current version
  label: "2.0",
  // Mendefinisikan tampilan label untuk versi yang sebelumnya di definisikan
  baseUrl: "/category/api-reg-course",
  // Route path dari hasil generate // kalo gak sesuai dengan url sidebar akan error // Leading slash is important
  // Hasil generate di versions.json
  versions: {
    "1.0": {
    // Menambahkan versi lainnya
      specPath: "apis/reg-course.yaml",
      outputDir: "docs/api/reg-course-versioned/1.0",
      // No trailing slash
      label: "Version 1.0",
      // Penulisan yang ingin ditampilkan pada label
      baseUrl: "/category/1.0/api-reg-course",
      // Leading slash is important
    },
  },
},
info

Pilih Versi yang terbaru yang menjadi API utama.

Define The Sidebar​

Setelah melakukan setup pada docusaurus, perlu lakukan setting di sidebar.js

const {
  versionSelector,
  versionCrumb,
} = require("docusaurus-plugin-openapi-docs/lib/sidebars/utils");
const regCourseVersions = require("./docs/api/reg-course-versioned/versions.json");

"reg-course-v2": [
  {
    type: "html",
    defaultStyle: true,
    value: versionSelector(regCourseVersions),
    className: "version-button",
  },
  {
    type: "html",
    defaultStyle: true,
    value: versionCrumb(`2.0`),
  },
  {
    type: "category",
    label: "Course",
    link: {
      type: "generated-index",
      title: "API Course",
      description: "API Course for Reguler environment",
      slug: "/category/api-reg-course",
    },
    // @ts-ignore
    items: require("./docs/api/reg-course-versioned/sidebar.ts"),
  },
],
"reg-course-v1": [
  {
    type: "html",
    defaultStyle: true,
    value: versionSelector(regCourseVersions),
    className: "version-button",
  },
  {
    type: "html",
    defaultStyle: true,
    value: versionCrumb(`1.0`),
  },
  {
    type: "category",
    label: "Course",
    link: {
      type: "generated-index",
      title: "API Course",
      description: "API Course for Reguler environment",
      slug: "/category/api-reg-course-v1",
    },
    // @ts-ignore
    items: require("./docs/api/reg-course-versioned/1.0/sidebar.ts"),
  },
],

Writer: Media