api_canon 0.2.3 → 0.2.4

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.
@@ -24,6 +24,9 @@ module ApiCanon
24
24
  end
25
25
  end
26
26
 
27
+ # When this module is included, your index method is overwritten with this one,
28
+ # which renders the ApiCanon documentation if params[:format] is html, and defaults
29
+ # to the existing method otherwise.
27
30
  def index
28
31
  if params[:format].blank? || params[:format] == 'html'
29
32
  api_canon_docs
@@ -33,13 +36,38 @@ module ApiCanon
33
36
  end
34
37
 
35
38
  module ClassMethods
36
- protected
39
+ # document_controller is used to describe your controller as a whole (Your API endpoint)
40
+ #
41
+ # == Example:
42
+ # document_controller as: 'Awesome Things' do
43
+ # describe "Here you can see all the awesome things, and get more details about the awesome things you're interested in."
44
+ # end
45
+ #
46
+ # @param opts [Hash] Optional, current options are:
47
+ # 'as' - An optional override for the controller name which defaults to controller_name.titleize
48
+ # @param block [&block] Begins the controller documentation DSL
49
+ # @see ApiCanon::Document#describe
37
50
  def document_controller(opts={}, &block)
38
51
  document = DocumentationStore.fetch controller_path
39
52
  document ||= Document.new controller_path, controller_name, opts
40
53
  document.instance_eval &block
41
54
  DocumentationStore.store document
42
55
  end
56
+
57
+ # document_method is used to describe the actions in your controller (your API actions)
58
+ #
59
+ # Example:
60
+ # document_method :index do
61
+ # describe "Gives you a list of awesome things!"
62
+ # param :foo, type: 'String', default: 'bar', example_values: Foo.limit(5).pluck(:name), description: 'foo is the type of awesome required'
63
+ # param :filter_level, type: 'Integer', default: 1, values: [1,2,3,4], description: 'filter_level can only be 1, 2, 3 or 4'
64
+ # end
65
+ #
66
+ # @param method_name [Symbol] The method to be documented
67
+ # @param block [block] Begins the action documentation DSL
68
+ # @see ApiCanon::DocumentedAction#describe
69
+ # @see ApiCanon::DocumentedAction#param
70
+ # @see ApiCanon::DocumentedAction#response_code
43
71
  def document_method(method_name,&block)
44
72
  document = DocumentationStore.fetch controller_path
45
73
  document ||= Document.new controller_path, controller_name
@@ -8,6 +8,10 @@ module ApiCanon
8
8
  self.display_name = opts[:as]
9
9
  @documented_actions = []
10
10
  end
11
+ # The describe method is used as a DSL method in the document_controller block,
12
+ # use it to describe your API endpoint as a whole.
13
+ # @see ApiCanon::ClassMethods#document_controller
14
+ # @param desc [String] The text to appear at the top of your API endpoint documentation page.
11
15
  def describe(desc)
12
16
  @description = desc
13
17
  end
@@ -1,3 +1,4 @@
1
+ require 'singleton'
1
2
  module ApiCanon
2
3
  # Replace this at the earliest possible opportunity
3
4
  # with something that stores stuff in Redis or something
@@ -16,6 +16,10 @@ module ApiCanon
16
16
  def response_code(code, options={})
17
17
  @response_codes[code] = options
18
18
  end
19
+ # The describe method is used as a DSL method in the document_action block,
20
+ # use it to describe your API endpoint as a whole.
21
+ # @see ApiCanon::ClassMethods#document_action
22
+ # @param desc [String] The text to appear at the top of your API endpoint documentation page.
19
23
  def describe(desc)
20
24
  @description = desc
21
25
  end
@@ -1,3 +1,3 @@
1
1
  module ApiCanon
2
- VERSION = '0.2.3'
2
+ VERSION = '0.2.4'
3
3
  end
metadata CHANGED
@@ -1,7 +1,8 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: api_canon
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.3
4
+ version: 0.2.4
5
+ prerelease:
5
6
  platform: ruby
6
7
  authors:
7
8
  - Cameron Walsh
@@ -13,20 +14,23 @@ dependencies:
13
14
  - !ruby/object:Gem::Dependency
14
15
  name: rails
15
16
  requirement: !ruby/object:Gem::Requirement
17
+ none: false
16
18
  requirements:
17
- - - '>='
19
+ - - ! '>='
18
20
  - !ruby/object:Gem::Version
19
21
  version: 2.3.17
20
22
  type: :runtime
21
23
  prerelease: false
22
24
  version_requirements: !ruby/object:Gem::Requirement
25
+ none: false
23
26
  requirements:
24
- - - '>='
27
+ - - ! '>='
25
28
  - !ruby/object:Gem::Version
26
29
  version: 2.3.17
27
30
  - !ruby/object:Gem::Dependency
28
31
  name: rspec
29
32
  requirement: !ruby/object:Gem::Requirement
33
+ none: false
30
34
  requirements:
31
35
  - - ~>
32
36
  - !ruby/object:Gem::Version
@@ -34,6 +38,7 @@ dependencies:
34
38
  type: :development
35
39
  prerelease: false
36
40
  version_requirements: !ruby/object:Gem::Requirement
41
+ none: false
37
42
  requirements:
38
43
  - - ~>
39
44
  - !ruby/object:Gem::Version
@@ -41,22 +46,23 @@ dependencies:
41
46
  - !ruby/object:Gem::Dependency
42
47
  name: rake
43
48
  requirement: !ruby/object:Gem::Requirement
49
+ none: false
44
50
  requirements:
45
- - - '>='
51
+ - - ! '>='
46
52
  - !ruby/object:Gem::Version
47
53
  version: '0'
48
54
  type: :development
49
55
  prerelease: false
50
56
  version_requirements: !ruby/object:Gem::Requirement
57
+ none: false
51
58
  requirements:
52
- - - '>='
59
+ - - ! '>='
53
60
  - !ruby/object:Gem::Version
54
61
  version: '0'
55
- description: |-
56
- api_canon is a declarative documentation generator
57
- for APIs. Declare the parameters and response codes,
58
- describe them, and give some example values. api_canon
59
- handles the rest for you.
62
+ description: ! "api_canon is a declarative documentation generator\n for
63
+ APIs. Declare the parameters and response codes,\n describe
64
+ them, and give some example values. api_canon\n handles the
65
+ rest for you."
60
66
  email:
61
67
  - cameron.walsh@gmail.com
62
68
  executables: []
@@ -91,26 +97,27 @@ files:
91
97
  homepage: http://github.com/cwalsh/api_canon
92
98
  licenses:
93
99
  - MIT
94
- metadata: {}
95
100
  post_install_message:
96
101
  rdoc_options: []
97
102
  require_paths:
98
103
  - lib
99
104
  required_ruby_version: !ruby/object:Gem::Requirement
105
+ none: false
100
106
  requirements:
101
- - - '>='
107
+ - - ! '>='
102
108
  - !ruby/object:Gem::Version
103
109
  version: '0'
104
110
  required_rubygems_version: !ruby/object:Gem::Requirement
111
+ none: false
105
112
  requirements:
106
- - - '>='
113
+ - - ! '>='
107
114
  - !ruby/object:Gem::Version
108
115
  version: '0'
109
116
  requirements: []
110
117
  rubyforge_project:
111
- rubygems_version: 2.0.3
118
+ rubygems_version: 1.8.25
112
119
  signing_key:
113
- specification_version: 4
120
+ specification_version: 3
114
121
  summary: Declarative documentation generator for APIs.
115
122
  test_files:
116
123
  - spec/spec_helper.rb
checksums.yaml DELETED
@@ -1,7 +0,0 @@
1
- ---
2
- SHA1:
3
- metadata.gz: 1fe88b5c318faea3491eed88a7679b503758363b
4
- data.tar.gz: e07f1ce662c6c7de16941a0bc17372f2e5c5e321
5
- SHA512:
6
- metadata.gz: b3ee1f26f4b745e920784701636eef94c250c2cc31a872d2eed3415300c254d48042bac7755440908373c436a05d5e0685f5215f79c40d1d251732673d74dd90
7
- data.tar.gz: 898a5e1b441f4783c9f6d2f5104cc3031f72fe6674e643ea200063196492f7d2cd9461dbf720583902b2358a5edfc55ca8602ff0774025deebe09daab67852d6