grape-docs 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: fa79525dbf182618343198bdd2ff041385867d24
4
- data.tar.gz: 9da8a00f46e9cd1a2de657a758c296520eee3c58
3
+ metadata.gz: 465f728453a8e41d834550bc9467295e54502fe3
4
+ data.tar.gz: b6d5e49f1a94e490c05b0ace14577873780a843f
5
5
  SHA512:
6
- metadata.gz: b30b2d791c79d77997d16429763b13fec561bfcdd1c265e47a5b4415c3eebca1237af94b7451da85f4d4a132fab2d91f32a6ecbc7e29b85a9bc9ae0977e91a91
7
- data.tar.gz: 6dc22119e4b6e8730e6a833a5503cc77ae7deb28b38c5f15c454f31640780e39d94283599d1fd0561f144d40477a4a5a409c2a490f9effce5fb91552521cc3b5
6
+ metadata.gz: e899b490b59ccb0ac0132d81194b900dd1f54b3846106cc63bbadf2be447b93e6823b7a2243cc427d8187804b316e3f6096c0145e35408e94bb64f961c0d50cb
7
+ data.tar.gz: 9a3e96715914e202b82ab9e18cf2794afd49c75032592e023bb355390057ecb782c7c6cf19ba67979298081aada92622362708046231d5bd83fce439b0f0a1f6
@@ -0,0 +1,6 @@
1
+ # <%= api.title %>
2
+
3
+ | **API Documentation** | **Availability** | **Status** |
4
+ | --- | --- | --- |
5
+ <% api.children.each do |endpoint| %>| [<%= api.title %> » <%= endpoint.title %>](<%= endpoint.path %>.md) | Premium Plan | Available |
6
+ <% end %>
@@ -0,0 +1,8 @@
1
+ # Table of contents
2
+
3
+ * [<%= api.title %>](README.md)
4
+
5
+ ## <%= api.title %>
6
+
7
+ <% api.children.each do |endpoint| %>* [<%= endpoint.title %>](<%= endpoint.path %>.md)
8
+ <% end %>
@@ -0,0 +1,28 @@
1
+ <% api.endpoints.each do |endpoint| %>
2
+ {% api "<%= endpoint.title %>", method="<%= endpoint.method %>", url="<%= endpoint.path %>" %}
3
+
4
+ **URL:** <%= endpoint.url %>
5
+
6
+ <%= endpoint.detail %>
7
+
8
+ ### Parameters:
9
+
10
+ <%= table(endpoint.params, :name, :type, :desc) do |param|
11
+ if param[:required]
12
+ param[:name] = "**#{param[:name]}**"
13
+ end
14
+ end %>
15
+ <% if endpoint.response %>
16
+
17
+ ### Response:
18
+
19
+ <%= json(endpoint.response) %>
20
+ <% end %>
21
+
22
+ {% endapi %}
23
+ <% end %>
24
+ <% if api.children.length > 0 %>
25
+ ## APIs
26
+ <% api.children.each do |child| %>
27
+ * [<%= child.title %>](<%= document_url(child)%>)<% end %>
28
+ <% end %>
@@ -3,27 +3,66 @@
3
3
  <%= api.detail %>
4
4
 
5
5
  <% api.endpoints.each do |endpoint| %>
6
- {% api "<%= endpoint.title %>", method="<%= endpoint.method %>", url="<%= endpoint.path %>" %}
6
+ {% api-method method="<%= endpoint.method.downcase %>" host="<%= endpoint.host %>" path="<%= endpoint.path %>" %}
7
7
 
8
- **URL:** <%= endpoint.url %>
8
+ {% api-method-summary %}
9
+ <%= endpoint.title %>
10
+ {% endapi-method-summary %}
9
11
 
12
+ {% api-method-description %}
10
13
  <%= endpoint.detail %>
14
+ {% endapi-method-description %}
11
15
 
12
- ### Parameters:
16
+ {% api-method-spec %}
13
17
 
14
- <%= table(endpoint.params, :name, :type, :desc) do |param|
15
- if param[:required]
16
- param[:name] = "**#{param[:name]}**"
17
- end
18
- end %>
19
- <% if endpoint.response %>
20
- ### Response:
18
+ {% api-method-request %}
21
19
 
22
- <%= json(endpoint.response) %>
20
+ <% if endpoint.path_params.length > 0 %>
21
+ {% api-method-path-parameters %}
22
+ <% endpoint.path_params.each do |param| %>
23
+ {% api-method-parameter name="<%= param[:name] %>" type="string" <% if param[:required] %>required=true <% end %>%}
24
+ <%= param[:desc] %>
25
+ {% endapi-method-parameter %}
26
+ <% end %>
27
+ {% endapi-method-path-parameters %}
28
+ <% end %>
29
+
30
+ <% if endpoint.query_params.length > 0 %>
31
+ {% api-method-query-parameters %}
32
+ <% endpoint.query_params.each do |param| %>
33
+ {% api-method-parameter name="<%= param[:name] %>" type="string" <% if param[:required] %>required=true <% end %>%}
34
+ <%= param[:desc] %>
35
+ {% endapi-method-parameter %}
36
+ <% end %>
37
+ {% endapi-method-query-parameters %}
38
+ <% end %>
39
+
40
+ <% if endpoint.body_params.length > 0 %>
41
+ {% api-method-body-parameters %}
42
+ <% endpoint.body_params.each do |param| %>
43
+ {% api-method-parameter name="<%= param[:name] %>" type="string" <% if param[:required] %>required=true <% end %>%}
44
+ <%= param[:desc] %>
45
+ {% endapi-method-parameter %}
46
+ <% end %>
47
+ {% endapi-method-body-parameters %}
23
48
  <% end %>
24
49
 
25
- {% endapi %}
50
+ {% endapi-method-request %}
51
+
52
+ {% api-method-response %}
53
+
54
+ {% api-method-response-example httpCode=<%= endpoint.status_code %> %}
55
+
56
+ <%= json(endpoint.response) %>
57
+ {% endapi-method-response-example %}
58
+
59
+ {% endapi-method-response %}
60
+
61
+ {% endapi-method-spec %}
62
+
63
+ {% endapi-method %}
26
64
  <% end %>
65
+
27
66
  <% if api.children.length > 0 %>
28
67
  ## APIs
29
68
  <% api.children.each do |child| %>
@@ -1,9 +1,10 @@
1
1
  module GrapeDocs
2
2
  class Api
3
- attr_reader :title, :detail, :path, :url, :endpoints, :children
3
+ attr_reader :title, :detail, :path, :url, :endpoints, :children, :public
4
4
 
5
5
  def initialize(grape)
6
6
  desc = grape.inheritable_setting.namespace[:description]
7
+ @public = desc[:public] || false
7
8
  @title = desc ? desc[:description] : grape.name.titlecase
8
9
  @detail = desc ? desc[:detail] : nil
9
10
  @path = File.join(grape.inheritable_setting.namespace_stackable[:mount_path])
@@ -12,7 +13,8 @@ module GrapeDocs
12
13
  @children = []
13
14
  grape.endpoints.each do |endpoint|
14
15
  if endpoint.options.key?(:app)
15
- @children.push(Api.new(endpoint.options[:app]))
16
+ api = Api.new(endpoint.options[:app])
17
+ @children.push(api) if api.public
16
18
  elsif endpoint.routes.count > 0
17
19
  @endpoints.push(Endpoint.new(self, endpoint))
18
20
  end
@@ -1,4 +1,3 @@
1
- require 'pry'
2
1
  require 'thor'
3
2
  require 'grape_docs'
4
3
  require 'grape_docs/version'
@@ -29,6 +28,8 @@ module GrapeDocs
29
28
 
30
29
  # export grape API
31
30
  exporter = Exporter.new(export_path)
31
+ exporter.export_summary(api)
32
+ exporter.export_readme(api)
32
33
  exporter.export(api)
33
34
  end
34
35
 
@@ -1,6 +1,6 @@
1
1
  module GrapeDocs
2
2
  class Endpoint
3
- attr_reader :title, :detail, :path, :url, :params, :method, :model, :response
3
+ attr_reader :title, :detail, :path, :url, :host, :params, :status_code, :method, :model, :response
4
4
 
5
5
  def initialize(api, endpoint)
6
6
  options = endpoint.options[:route_options]
@@ -8,12 +8,41 @@ module GrapeDocs
8
8
  @detail = options[:detail]
9
9
  parent_path = File.join(endpoint.inheritable_setting.namespace_stackable[:mount_path])
10
10
  @path = File.join(parent_path, endpoint.options[:path].first.to_s)
11
- @url = File.join(GrapeDocs.config[:api_host], @path)
11
+ @host = GrapeDocs.config[:api_host]
12
+ @url = File.join(@host, @path)
12
13
  @params = options[:params].map { |p| p[1].merge(name: p[0]) }
13
14
  @method = endpoint.options[:method].first
15
+ @status_code = 200
14
16
  if options[:entity]
15
- @model = options[:entity].documentation.map { |p| p[1].merge(name: p[0]) }
16
- @response = build_response(@model)
17
+ entity = options[:entity].kind_of?(Array) ? options[:entity][1] : options[:entity]
18
+ @status_code = options[:entity].kind_of?(Array) ? options[:entity][0] : 200
19
+ unless entity.nil?
20
+ @model = entity.documentation.map { |p| p[1].merge(name: p[0]) }
21
+ @response = build_response(@model)
22
+ end
23
+ end
24
+ end
25
+
26
+ def path_params
27
+ names = path.scan(/:([a-z0-9_]+)/).map(&:first)
28
+ params.select do |param|
29
+ names.include?(param[:name])
30
+ end
31
+ end
32
+
33
+ def body_params
34
+ return [] if method == "GET"
35
+ names = path.scan(/:([a-z0-9_]+)/).map(&:first)
36
+ params.reject do |param|
37
+ names.include?(param[:name])
38
+ end
39
+ end
40
+
41
+ def query_params
42
+ return [] if method != "GET"
43
+ names = path.scan(/:([a-z0-9_]+)/).map(&:first)
44
+ params.reject do |param|
45
+ names.include?(param[:name])
17
46
  end
18
47
  end
19
48
 
@@ -7,17 +7,19 @@ module GrapeDocs
7
7
 
8
8
  # load template
9
9
  filename = "#{GrapeDocs.config[:template]}.md.erb"
10
- current_dir = Workspace.dir(Dir.pwd)
11
- template_file = current_dir.file(filename)
12
- unless template_file.exists?
13
- spec = Gem::Specification.find_by_name("grape-docs")
14
- assets_dir = Workspace::Dir.new(spec.gem_dir).dir("assets")
15
- template_file = assets_dir.file(filename)
16
- unless template_file.exists?
17
- template_file = assets_dir.file("default.md.erb")
18
- end
19
- end
20
- @template = ERB.new(template_file.read, nil, "%")
10
+ @template = load_template(filename)
11
+ end
12
+
13
+ def export_summary(api)
14
+ summary_template = load_template("generic/SUMMARY.md.erb")
15
+ result = summary_template.result(binding).gsub(/\n\n\n/, "\n\n")
16
+ root.file("SUMMARY.md").write(result)
17
+ end
18
+
19
+ def export_readme(api)
20
+ readme_template = load_template("generic/README.md.erb")
21
+ result = readme_template.result(binding).gsub(/\n\n\n/, "\n\n")
22
+ root.file("README.md").write(result)
21
23
  end
22
24
 
23
25
  def export(api)
@@ -58,5 +60,21 @@ module GrapeDocs
58
60
  path = target.path.sub(%r{^/}, '')
59
61
  "#{path}.md"
60
62
  end
63
+
64
+ private
65
+
66
+ def load_template(filename, default_filename = "default.md.erb")
67
+ current_dir = Workspace.dir(Dir.pwd)
68
+ template_file = current_dir.file(filename)
69
+ unless template_file.exists?
70
+ spec = Gem::Specification.find_by_name("grape-docs")
71
+ assets_dir = Workspace::Dir.new(spec.gem_dir).dir("assets")
72
+ template_file = assets_dir.file(filename)
73
+ unless template_file.exists?
74
+ template_file = assets_dir.file(default_filename)
75
+ end
76
+ end
77
+ ERB.new(template_file.read, nil, "%")
78
+ end
61
79
  end
62
80
  end
@@ -1,3 +1,3 @@
1
1
  module GrapeDocs
2
- VERSION = "1.0.2"
2
+ VERSION = "1.0.3"
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: grape-docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.2
4
+ version: 1.0.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tobias Strebitzer
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2018-01-24 00:00:00.000000000 Z
11
+ date: 2018-05-09 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -117,6 +117,9 @@ extra_rdoc_files: []
117
117
  files:
118
118
  - README.md
119
119
  - assets/default.md.erb
120
+ - assets/generic/README.md.erb
121
+ - assets/generic/SUMMARY.md.erb
122
+ - assets/gitbook-legacy.md.erb
120
123
  - assets/gitbook.md.erb
121
124
  - bin/grape-docs
122
125
  - lib/grape_docs.rb