jekyll-hk-api-doc 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9998a7b6bdd04956e5ec0a361565fe36a4dee78d779ad56ad5552bacb1ab89b5
-  data.tar.gz: c886dd85c417b544a862a73342d8f9e100abd5ac2f93ac922f6144000ad081c5
+  metadata.gz: 806d12a4a70e3962c2f4ea25d33a7c2c053b2a47f95771a54bdf2f95b4cdfe78
+  data.tar.gz: 6a2c924a09210dffd947d214b92816e26f20706c8a259d2b92d246026e843714
 SHA512:
-  metadata.gz: 0d927449f04fab1aa160fb794f2258b26a4094897fc838053d2f48ae8461262ce5d5ea6ead955e867098a11e44ffdcf4c3f949aef4bb5746a9830f57a45dee63
-  data.tar.gz: cff3d5c648a9e3f1fda34b5fa7f789d1c3f271a64811bbeac646333f895d1b507347ccbc88f169589310674fee432c3d0f7ff6b10d64510943e53384683578e0
+  metadata.gz: efb517671a86061da99e180741836f5be7c9d75604c2d800ac96fcd70ce8eb707ec3cb7145011c611c8c6c833e68d90a155eecac4e0ee260a55d92ea6a97c412
+  data.tar.gz: 2625b14c3d809566dc285ea1e562f451335792f302c4a49f7cf05dcde61dba21414a442ace86525ed68037b4075c856f069cdf08e99642aa35f93d0d330425ba

data/README.md

@@ -1,30 +1,83 @@
-# jekyll-hk-api-doc
+# jekyll-hk-api-doc [v1.0.1]
 
 A Simple API Doc with YAML powered by Jekyll
-
 ## Installation
 
-1. Add the line below to your Jekyll site's `Gemfile`:
+1. Add the line below to your Jekyll site's `Gemfile`.
 
 ```ruby
 gem "jekyll-hk-api-doc"
 ```
 
-2. Add the line below to your Jekyll site's `_config.yml`:
+2. Install the gem with either one of commands below.
 
-```yaml
-theme: jekyll-hk-api-doc
+```bash
+$ bundle install
+$ gem install jekyll-hk-api-doc
 ```
 
-3. Create data directory `_api` and update `_config.yml`:
+3. Update your Jekyll site's `_config.yml`. Keys listed below are used by `jekyll-hk-api-doc` theme.
 
 ```yaml
+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]
 ```
 
-4. Write yaml in the data directory. Example:
+4. 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
+
+5. Write yaml in `_api/`. Available keys for yaml is listed below:
+
+```yaml
+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)]
+```
 
 ```yaml
+# Example
 name: Auth
 description: APIs for authentication
 base_url: /api/auth
@@ -34,7 +87,6 @@ apis:
     method: post
     description: |
       Issue <code>access token</code> and <code>refresh token</code>
-      * Currently, the api is using <code>http</code> and it does have vulnerability of sending plain password, but it will soon be updated to <code>https</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:
@@ -57,87 +109,9 @@ apis:
             - 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.
-  - name: ID Duplication Check
-    url: /id-duplicate-check
-    method: get
-    description: Checks if new <code>id</code> is duplicated or not
-    params:
-      query:
-        - name: id
-          is_required: true,
-          type: string
-          description: ID
-    response: 
-      success:
-        - status_code: 200
-          description: <code>id</code> is not duplicated(good to use)
-      fail: 
-        - status_code: 400
-          description: <code>id</code> is duplicated(not good to use)
-  - name: Sign Up
-    url: /signup
-    method: post
-    description: Create a new account.
-    params:
-      body: 
-        - name: id
-          is_required: true
-          type: string
-          description: ID
-        - name: pw
-          is_required: true
-          type: string
-          description: (plain) Password
-        - name: nickname
-          is_required: true
-          type: string
-          description: Nickname
-        - name: email
-          is_required: true
-          type: string
-          description: Email
-        - name: age
-          is_required: true
-          type: int
-          description: Age
-    response: 
-      success:
-        - status_code: 200
-          description: New account has been successfully created.
-      fail: 
-        - status_code: 400
-          description: |
-            - Either one of <code>id</code>, <code>pw</code>, <code>nickname</code>, <code>email</code> or <code>age</code> is not included in the request or not a proper type.
-            - <code>id</code> already registered(duplicated id)
-  - name: Refresh Token
-    url: /refresh
-    method: get
-    description: |
-      Re-issue an access token with <code>refresh token</code>
-    params:
-      header: 
-        - name: x-access-token
-          is_required: true
-          type: string
-          description: (expired) access token
-        - name: x-refresh-token
-          is_required: true
-          type: string
-          description: refresh token
-    response: 
-      success:
-        - status_code: 200
-          example: auth-refreshtoken-200
-      fail: 
-        - status_code: 401
-          description: |
-            - <code>x-access-token</code> or <code>x-refresh-token</code> is not provided.
-            - <code>x-access-token</code> or <code>x-refresh-token</code> is not valid(not issued by the server, or modified).
-            - <code>x-refresh-token</code> is banned.
-            - <code>x-access-token</code> and <code>x-refresh-token</code> are not matching.
 ```
 
-5. Execute the python code below with Python 3:
+6. Execute the python code below with Python 3, which creates html files in `documents/_api_book_page` corresponding to yaml files in `_api`.
 
 ```python
 import os
@@ -158,35 +132,18 @@ yamls = sorted([os.path.splitext(x)[0] for x in os.listdir(yaml_path) if x.endsw
 for i, yaml in enumerate(yamls):
     with open(os.path.join(html_path, f"{yaml}.html"), "w") as html:
         html.write("---\n")
-        
-        if i == 0:
-            redirect_from = "redirect_from:\n    - /\n    - docs/\n"
-            html.write(redirect_from)
-
         html.write("---\n")
 ```
 
-6. Execute:
-
-    $ bundle
+7. Test:
 
-Or install it yourself as:
-
-    $ gem install jekyll-hk-api-doc
+```bash
+$ bundle exec jekyll serve
+```
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/HeekangPark/jekyll-hk-api-doc.
-
-## Development
-
-To set up your environment to develop this theme, run `bundle install`.
-
-Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
-
-When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
-To add a custom directory to your theme-gem, please edit the regexp in `jekyll-hk-api-doc.gemspec` accordingly.
-
 ## License
 
-The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/_includes/api_main_content.html

@@ -10,7 +10,7 @@
             <div class="api-name-area" id="api-{{ forloop.index }}">
                 <h2 class="api-name">{{ api.name }}</h2>
                 <p class="api-method api-method-{{ api.method | downcase }}">{{ api.method | upcase }}</p>
-                <p class="api-url-area"><span class="api-baseurl">{{ site.api_baseurl | escape }}</span><span class="api-url">{{ yaml.base_url | escape }}{{ api.url | escape }}</span></p>
+                <p class="api-url-area"><span class="api-baseurl">{{ site.api_baseurl | escape }}</span><span class="api-url">{{ yaml.baseurl | escape }}{{ api.url | escape }}</span></p>
             </div>
             
             <div class="api-description">{{ api.description | newline_to_br }}</div>
@@ -172,8 +172,6 @@
                                     : Bad Request
                                     {% elsif item.status_code == 401 %}
                                     : Unauthorized
-                                    {% elsif item.status_code == 401 %}
-                                    : Unauthorized
                                     {% elsif item.status_code == 403 %}
                                     : Forbidden
                                     {% elsif item.status_code == 404 %}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-hk-api-doc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Heekang Park
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-14 00:00:00.000000000 Z
+date: 2021-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll