jekyll-hk-api-doc [v1.1.2]

theme: jekyll-hk-api-doc
assets: /assets
data_dir: _api
collections_dir: documents
collections:
  api_book_pages:
    output: true
    permalink: /:name
defaults:
  - scope:
      path: ""
      type: "api_book_page"
    values:
      layout: "api"
      
title: [Your Jekyll site's title]
description: [Your Jekyll site's description]
baseurl: [Your Jekyll site's base url. If base url not exists, it should be ""(empty string)]
author: [Author's name]
email: [Author's email]

api_baseurl: [API baseurl. This will be prepended on every API's url.]
version: [API version]

name: [Name of the API sets]
description: [Description of the API sets]
baseurl: [base_url will be prepended to all APIs in the set.]
apis:
  - name: [Name of the API]
    url: [URL of the API. The full URL will be (api_baseurl at _config.yml) + (baseurl at yaml) + (url).]
    method: [Request method. Available values are "get", "post", "put", "delete", "patch", "head", "options".]
    description: [Description of the API]
    params:
      body: [Type of parameters. Available values are "header", "path", "query", "body".]
        - name: [Name of the parameter]
          is_required: [Available values are "true", "false". If "true", "required" tag will be displayed for the parameter. If "false", "optional" will be displayed for the parameter.]
          type: [Type of the parameter]
          description: [Description of the parameter]
    response:
      success:
        - status_code: [Http response code. If "200", "Success" will be displayed.]
          description: [Description of the response]
          example: [Response example. For design purpose, I seperate yaml and example(examples are loaded via ajax, and highlight.js is applied to them). You only have to write the name of the json file in assets/api/examples/ directory(without the extension .json)]
      fail:
        - status_code: [Http response code. If "400", "Bad Request" will be displayed. If "401", "Unauthorized" will be displayed. If "403", "Forbidden" will be displayed. If "404", "Not Found" will be displayed.]
          description: [Description of the response]
          example: [Response example. For design purpose, I seperate yaml and example(examples are loaded via ajax, and highlight.js is applied to them). You only have to write the name of the json file in assets/api/examples/ directory(without the extension .json)]

# Example
name: Auth
description: APIs for authentication
base_url: /api/auth
apis:
  - name: Sign In
    url: /signin
    method: post
    description: |
      Issue <code>access token</code> and <code>refresh token</code>
      * <code>access token</code>s will be expired 10 minutes after they are issued.
      * <code>refresh token</code>s will be expired 2 weeks after they are issued.
    params:
      body:
        - name: id
          is_required: true
          type: string
          description: ID
        - name: pw
          is_required: true
          type: string
          description: (plain) password
    response:
      success:
        - status_code: 200
          example: auth-signin-200
      fail:
        - status_code: 400
          description: |
            - Either one of <code>id</code> or <code>pw</code> is not included in the request.
            - <code>id</code> is not registered.
            - <code>id</code> and <code>pw</code> are not matching.