oas_rails 0.5.0 → 0.7.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b3f5da00f122856b6cce2f73b5912013477726bda80f57f39fdbe4609bc551c7
4
- data.tar.gz: 35def82214e4c8b01755ddb2b501140f45ab653d575512ec52730d5722f7b025
3
+ metadata.gz: 52858aae429b158f26e303387df144ff64845bb420e7abc329495c6c984a5f2a
4
+ data.tar.gz: 39ed4dbc661f79d9ecc289900004ae18a07726300762beabffca1714b2f9de8f
5
5
  SHA512:
6
- metadata.gz: f6854cfb18a0770b11dae6e87da5a7a5d3521d3967bd27656cf6e69ac3f3dfb8342b045f04af2ba27ab969e1b5615dd757fb26e9632628811741f0876f473a94
7
- data.tar.gz: 994dc70c3ba5b1a935686b9f7c90913bd59106d8981db340f788d38d048226f1acef0eb113d2e12534c5eec83d7a5ee8d9fd159da923bbcbd412e8d72a9eb758
6
+ metadata.gz: 2666274a5c7fe0656adef0a5d56593885f4f85eccfe7a4c4708d29e2a86f7f79afb5d830a97e7ff6902cab8f554243b2302b4887b82efcbc3111150d784ee385
7
+ data.tar.gz: c12f2cde7a1f1ce6cf2ff950971e50de455f9938456ad423d2235916c121972b5c4dbe08a873dd0dd57ee2878f59d11a2a9dca0ee8301fd433582e03bcf0a844
data/README.md CHANGED
@@ -164,13 +164,13 @@ Documents the request body needed by the endpoint. The structure is optional if
164
164
 
165
165
  **Example**:
166
166
 
167
- `# @request_body The user to be created [!Hash{user: {name: String, age: Integer, password: String}}]`
167
+ `# @request_body The user to be created [!Hash{user: Hash{name: String, age: Integer, password: String}}]`
168
168
 
169
169
  `# @request_body The user to be created [!User]`
170
170
 
171
171
  `# @request_body The user to be created [User]`
172
172
 
173
- `# @request_body The user to be created [!Hash{user: {name: String, age: Integer, password: String, surnames: Array<String>, coords: Hash{lat: String, lng: String}}}]`
173
+ `# @request_body The user to be created [!Hash{user: Hash{name: String, age: Integer, password: String, surnames: Array<String>, coords: Hash{lat: String, lng: String}}}]`
174
174
 
175
175
  </details>
176
176
 
@@ -197,7 +197,22 @@ Documents the responses of the endpoint and overrides the default responses foun
197
197
 
198
198
  `# @response User not found by the provided Id(404) [Hash{success: Boolean, message: String}]`
199
199
 
200
- `# @response Validation errors(422) [Hash{success: Boolean, erros: Array<Hash{field: String, type: String, detail: Array<String>}>}]`
200
+ `# @response Validation errors(422) [Hash{success: Boolean, errors: Array<Hash{field: String, type: String, detail: Array<String>}>}]`
201
+
202
+ </details>
203
+
204
+ <details>
205
+ <summary style="font-weight: bold; font-size: 1.2em;">@response_example</summary>
206
+
207
+ **Structure**: `@response_example text(code) [String Hash]`
208
+
209
+ Documents response examples of the endpoint associated to a response code.
210
+
211
+ **Example**:
212
+
213
+ `# @response_example Invalida Email(422) [{success: "false", errors: [{field: "email", type: "email", detail: ["Invalid email"]}] }]`
214
+
215
+ `# @response_example Id not exists (404) [{success: "false", message: "Nothing found with the provided ID." }]`
201
216
 
202
217
  </details>
203
218
 
@@ -1,7 +1,7 @@
1
1
  <!DOCTYPE html>
2
2
  <html>
3
3
  <head>
4
- <title>Oas rails</title>
4
+ <title><%= OasRails.config.info.title %></title>
5
5
  <%= csrf_meta_tags %>
6
6
  <%= csp_meta_tag %>
7
7
  <meta charset="utf-8">
@@ -9,11 +9,11 @@
9
9
  <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
10
10
  </head>
11
11
  <body>
12
- <rapi-doc
13
- spec-url = "<%= OasRails::Engine.routes.find_script_name({}) %>.json"
14
- theme = "dark"
12
+ <rapi-doc
13
+ spec-url = "<%= OasRails::Engine.routes.find_script_name({}) %>.json"
14
+ theme = "dark"
15
15
  bg-color="#0F172A"
16
- text-color= "#f7f7f7"
16
+ text-color= "#f7f7f7"
17
17
  show-header = 'false'
18
18
  primary-color = "#2de410"
19
19
  font-size="largest"
@@ -21,7 +21,7 @@
21
21
  nav-text-color="#f7f7f7"
22
22
  nav-item-spacing="relaxed"
23
23
  allow-spec-file-download="true"
24
- >
24
+ >
25
25
  </rapi-doc>
26
26
  </body>
27
27
  </html>
@@ -2,6 +2,7 @@
2
2
  OasRails.configure do |config|
3
3
  # Basic Information about the API
4
4
  config.info.title = 'OasRails'
5
+ config.info.version = '1.0.0'
5
6
  config.info.summary = 'OasRails: Automatic Interactive API Documentation for Rails'
6
7
  config.info.description = <<~HEREDOC
7
8
  # Welcome to OasRails
@@ -8,7 +8,10 @@ module OasRails
8
8
 
9
9
  def from_oas_route(oas_route)
10
10
  oas_route.docstring.tags(:response).each do |tag|
11
- @responses.add_response(ResponseBuilder.new(@specification).from_tag(tag).build)
11
+ content = ContentBuilder.new(@specification, :outgoing).with_schema(tag.schema).with_examples_from_tags(oas_route.docstring.tags(:response_example).filter { |re| re.code == tag.name }).build
12
+ response = ResponseBuilder.new(@specification).with_code(tag.name.to_i).with_description(tag.text).with_content(content).build
13
+
14
+ @responses.add_response(response)
12
15
  end
13
16
 
14
17
  self
@@ -26,7 +26,7 @@ module OasRails
26
26
  @security_schemas = {}
27
27
  @set_default_responses = true
28
28
  @possible_default_responses = [:not_found, :unauthorized, :forbidden]
29
- @response_body_of_default = "{ message: String }"
29
+ @response_body_of_default = "Hash{ success: !Boolean, message: String }"
30
30
  end
31
31
 
32
32
  def security_schema=(value)
@@ -1,3 +1,3 @@
1
1
  module OasRails
2
- VERSION = "0.5.0"
2
+ VERSION = "0.7.0"
3
3
  end
@@ -0,0 +1,12 @@
1
+ module OasRails
2
+ module YARD
3
+ class ExampleTag < ::YARD::Tags::Tag
4
+ attr_accessor :content
5
+
6
+ def initialize(tag_name, text, content: {})
7
+ super(tag_name, text, nil, nil)
8
+ @content = content
9
+ end
10
+ end
11
+ end
12
+ end
@@ -37,6 +37,15 @@ module OasRails
37
37
  ResponseTag.new(tag_name, code, name, schema)
38
38
  end
39
39
 
40
+ # Parses a tag that represents a response example.
41
+ # @param tag_name [String] The name of the tag.
42
+ # @param text [String] The tag text to parse.
43
+ # @return [ResponseExampleTag] The parsed response example tag object.
44
+ def parse_tag_with_response_example(tag_name, text)
45
+ description, code, hash = extract_name_code_and_hash(text)
46
+ ResponseExampleTag.new(tag_name, description, content: hash, code:)
47
+ end
48
+
40
49
  private
41
50
 
42
51
  # Reusable method for extracting description, type, and content with an option to process content.
@@ -44,7 +53,7 @@ module OasRails
44
53
  # @param process_content [Boolean] Whether to evaluate the content as a hash.
45
54
  # @return [Array] An array containing the description, type, and content or remaining text.
46
55
  def extract_description_type_and_content(text, process_content: false)
47
- match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
56
+ match = text.match(/^(.*?)\s*\[(.*)\]\s*(.*)$/)
48
57
  raise ArgumentError, "Invalid tag format: #{text}" if match.nil?
49
58
 
50
59
  description = match[1].strip
@@ -84,6 +93,16 @@ module OasRails
84
93
  [name, code, schema]
85
94
  end
86
95
 
96
+ # Specific method to extract name, code, and hash for responses examples.
97
+ # @param text [String] The text to parse.
98
+ # @return [Array] An array containing the name, code, and schema.
99
+ def extract_name_code_and_hash(text)
100
+ name, code = extract_text_and_parentheses_content(text)
101
+ _, type, = extract_description_type_and_content(text)
102
+ hash = eval_content(type)
103
+ [name, code, hash]
104
+ end
105
+
87
106
  # Evaluates a string as a hash, handling errors gracefully.
88
107
  # @param content [String] The content string to evaluate.
89
108
  # @return [Hash] The evaluated hash, or an empty hash if an error occurs.
@@ -1,11 +1,10 @@
1
1
  module OasRails
2
2
  module YARD
3
- class RequestBodyExampleTag < ::YARD::Tags::Tag
3
+ class RequestBodyExampleTag < ExampleTag
4
4
  attr_accessor :content
5
5
 
6
6
  def initialize(tag_name, text, content: {})
7
- super(tag_name, text, nil, nil)
8
- @content = content
7
+ super
9
8
  end
10
9
  end
11
10
  end
@@ -0,0 +1,12 @@
1
+ module OasRails
2
+ module YARD
3
+ class ResponseExampleTag < ExampleTag
4
+ attr_accessor :code
5
+
6
+ def initialize(tag_name, text, content: {}, code: 200)
7
+ super(tag_name, text, content:)
8
+ @code = code
9
+ end
10
+ end
11
+ end
12
+ end
@@ -3,6 +3,7 @@ module OasRails
3
3
  class ResponseTag < ::YARD::Tags::Tag
4
4
  attr_accessor :schema
5
5
 
6
+ # TODO: name == code. The name MUST be changed to code for better understanding
6
7
  def initialize(tag_name, name, text, schema)
7
8
  super(tag_name, text, nil, name)
8
9
  @schema = schema
data/lib/oas_rails.rb CHANGED
@@ -47,9 +47,11 @@ module OasRails
47
47
 
48
48
  module YARD
49
49
  autoload :RequestBodyTag, 'oas_rails/yard/request_body_tag'
50
+ autoload :ExampleTag, 'oas_rails/yard/example_tag'
50
51
  autoload :RequestBodyExampleTag, 'oas_rails/yard/request_body_example_tag'
51
52
  autoload :ParameterTag, 'oas_rails/yard/parameter_tag'
52
53
  autoload :ResponseTag, 'oas_rails/yard/response_tag'
54
+ autoload :ResponseExampleTag, 'oas_rails/yard/response_example_tag'
53
55
  autoload :OasRailsFactory, 'oas_rails/yard/oas_rails_factory'
54
56
  end
55
57
 
@@ -84,6 +86,7 @@ module OasRails
84
86
  'Request body Example' => [:request_body_example, :with_request_body_example],
85
87
  'Parameter' => [:parameter, :with_parameter],
86
88
  'Response' => [:response, :with_response],
89
+ 'Response Example' => [:response_example, :with_response_example],
87
90
  'Endpoint Tags' => [:tags],
88
91
  'Summary' => [:summary],
89
92
  'No Auth' => [:no_auth],
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: oas_rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - a-chacon
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2024-08-23 00:00:00.000000000 Z
11
+ date: 2024-08-27 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: method_source
@@ -130,10 +130,12 @@ files:
130
130
  - lib/oas_rails/spec/tag.rb
131
131
  - lib/oas_rails/utils.rb
132
132
  - lib/oas_rails/version.rb
133
+ - lib/oas_rails/yard/example_tag.rb
133
134
  - lib/oas_rails/yard/oas_rails_factory.rb
134
135
  - lib/oas_rails/yard/parameter_tag.rb
135
136
  - lib/oas_rails/yard/request_body_example_tag.rb
136
137
  - lib/oas_rails/yard/request_body_tag.rb
138
+ - lib/oas_rails/yard/response_example_tag.rb
137
139
  - lib/oas_rails/yard/response_tag.rb
138
140
  homepage: https://github.com/a-chacon/oas_rails
139
141
  licenses: