jekyll-hk-api-doc [v1.1.0]¶ ↑
A Simple API Doc with YAML powered by Jekyll
Demopage: 2020swchallenge-moai.github.io/docs
Installation¶ ↑
-
Add the line below to your Jekyll site's
Gemfile
.
gem "jekyll-hk-api-doc"
-
Install the gem with either one of commands below.
$ bundle install $ gem install jekyll-hk-api-doc
-
Update your Jekyll site's
_config.yml
. Keys listed below are used byjekyll-hk-api-doc
theme.
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]
-
Create directories:
_api/
,assets/api/examples/
-
_api/
: Directory where yaml files will be stored -
assets/api/examples/
: Directory where the response examples(in json) of apis's will be stored -
Write yaml in
_api/
. Available keys for yaml is listed below:
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.
-
Execute the python code below with Python 3, which creates html files in
documents/_api_book_page
corresponding to yaml files in_api
.
import os yaml_path = "_api" html_path = "documents/_api_book_page" if not os.path.exists(yaml_path): os.mkdir(yaml_path) if not os.path.exists(html_path): os.mkdir(html_path) for html in os.listdir(html_path): os.remove(os.path.join(html_path, html)) yamls = sorted([os.path.splitext(x)[0] for x in os.listdir(yaml_path) if x.endswith(".yaml")]) for i, yaml in enumerate(yamls): with open(os.path.join(html_path, f"{yaml}.html"), "w") as html: html.write("---\n") html.write("---\n")
-
Test:
$ bundle exec jekyll serve
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub at github.com/HeekangPark/jekyll-hk-api-doc.
License¶ ↑
The theme is available as open source under the terms of the MIT License.
Version Log¶ ↑
v1.0.0¶ ↑
Accidently commited. Currently yanked.
v1.0.1¶ ↑
First version.
v1.1.0¶ ↑
-
support list(
<ul>
,<ol>
) in description keys -
support markdown in description keys