Add Paths in OpenAPI generator #1297

dhamo-ror · 2025-09-13T05:46:39Z

Hi @agrare, could you kindly review this PR and let me know your suggestions.

agrare · 2025-09-15T13:08:56Z

lib/manageiq/api/open_api/generator.rb

+        def get_model_class(klass)
+          case klass
+          when String
+            begin
+              klass.constantize
+            rescue NameError => e
+              puts "Warning: Could not constantize #{klass}: #{e.message}"
+              nil
+            end
+          when Class
+            klass
+          else
+            nil
+          end
+        end


This looks like it could be just klass = klass.safe_constantize if klass.kind_of?(String)
If we don't need to handle Class or String and only String then we could use safe_constantize directly.

NOTE I threw a breakpoint in else and Class and no instances of that so I think we can do collection.klass&.safe_constantize below

Fryguy · 2025-09-15T13:14:04Z

lib/manageiq/api/open_api/generator.rb

+                      "properties" => {
+                        "name" => {"type" => "string", "example" => collection_name},
+                        "count" => {"type" => "integer", "description" => "Total number of resources"},
+                        "subcount" => {"type" => "integer", "description" => "Number of resources returned"},


Very minor

Suggested change

"subcount" => {"type" => "integer", "description" => "Number of resources returned"},

"subcount" => {"type" => "integer", "description" => "Number of resources returned after filters applied"},

Fryguy · 2025-09-15T13:14:22Z

lib/manageiq/api/open_api/generator.rb

+                      "type" => "object",
+                      "properties" => {
+                        "name" => {"type" => "string", "example" => collection_name},
+                        "count" => {"type" => "integer", "description" => "Total number of resources"},


Suggested change

"count" => {"type" => "integer", "description" => "Total number of resources"},

"count" => {"type" => "integer", "description" => "Total number of resources without filters applied"},

Fryguy · 2025-09-15T13:16:00Z

lib/manageiq/api/open_api/generator.rb

+              "404" => {"description" => "Resource not found"},
+              "401" => {"description" => "Unauthorized"},
+              "403" => {"description" => "Forbidden"}


Very minor, but let's sort these.

Suggested change

"404" => {"description" => "Resource not found"},

"401" => {"description" => "Unauthorized"},

"403" => {"description" => "Forbidden"}

"401" => {"description" => "Unauthorized"},

"403" => {"description" => "Forbidden"},

"404" => {"description" => "Resource not found"}

agrare · 2025-09-15T13:19:22Z

lib/manageiq/api/open_api/generator.rb

+          collection.respond_to?(:collection_actions) && 
+          collection.collection_actions&.key?(action)


Suggested change

collection.respond_to?(:collection_actions) &&

collection.collection_actions&.key?(action)

collection.respond_to?(:collection_actions) &&

collection.collection_actions&.key?(action)

agrare · 2025-09-15T13:19:31Z

lib/manageiq/api/open_api/generator.rb

+          collection.respond_to?(:resource_actions) && 
+          collection.resource_actions&.key?(action)


Suggested change

collection.respond_to?(:resource_actions) &&

collection.resource_actions&.key?(action)

collection.respond_to?(:resource_actions) &&

collection.resource_actions&.key?(action)

lib/manageiq/api/open_api/generator.rb

agrare · 2025-09-15T13:20:19Z

lib/manageiq/api/open_api/generator.rb

+        def build_update_schema(model_class, schema_name)
+          properties = build_writable_properties(model_class)
+          # Make all properties optional for PATCH
+          properties.each { |_, prop| prop.delete("required") if prop.is_a?(Hash) }


Suggested change

properties.each { |_, prop| prop.delete("required") if prop.is_a?(Hash) }

properties.each_value { |prop| prop.delete("required") if prop.is_a?(Hash) }

Fryguy · 2025-09-15T13:21:00Z

lib/manageiq/api/open_api/generator.rb

+          if collection.respond_to?(:resource_actions) && collection.resource_actions
+            collection.resource_actions.keys
+          else
+            []
+          end


Suggested change

if collection.respond_to?(:resource_actions) && collection.resource_actions

collection.resource_actions.keys

else

[]

end

collection.try(:resource_actions)&.keys || []

agrare · 2025-09-15T13:21:04Z

lib/manageiq/api/open_api/generator.rb

+            next unless collection.klass
+
+            # Skip if we can't get a valid model class
+            model_class = get_model_class(collection.klass)
+            next unless model_class


If this is always a string we could do

model_class = collection.klass&.safe_constantize next if model_class.nil?

Fryguy · 2025-09-15T13:29:28Z

lib/manageiq/api/open_api/generator.rb

+            "subcoll_id" => {
+              "name" => "subcoll_id",


I think this should be spelled out here.

Suggested change

"subcoll_id" => {

"name" => "subcoll_id",

"subcollection_id" => {

"name" => "subcollection_id",

agrare · 2025-09-15T13:38:51Z

lib/manageiq/api/open_api/generator.rb

+          # POST collection - if creation is supported
+          if supports_collection_action?(collection, :post)
+            operations["post"] = {
+              "summary" => "Create #{collection_name.to_s.singularize}",


I think we need to check the collection_actions here because not every POST on the collection creates the resource.

Example: VMs has a lot of collection_actions but none of them are :name: create

Hi @agrare, I request your input on this to proceed further.

I think it could be similar to the resource_actions you have down here https://github.com/ManageIQ/manageiq-api/pull/1297/files#diff-d14d325d93f1febc7f776ea58816bce4c5b74cd4b3c09b883a2dd2c82889857bR289

like this @agrare?,

# POST collection - only if creation is supported if collection.collection_actions&.key?(:create) operations["post"] = { "summary" => "Create #{collection_name.to_s.singularize}", "description" => "Create a new #{collection_name.to_s.singularize}", "requestBody" => { "required" => true, "content" => { "application/json" => { "schema" => build_create_schema(model_class, schema_name) } } }, "responses" => { "201" => { "description" => "Resource created successfully", "content" => { "application/json" => { "schema" => {"$ref" => "##{SCHEMAS_PATH}/#{schema_name}"} } } }, "400" => {"description" => "Bad Request - Invalid input"}, "401" => {"description" => "Unauthorized"}, "403" => {"description" => "Forbidden"}, "422" => {"description" => "Unprocessable Entity - Validation errors"} }, "tags" => [collection_name.to_s.titleize] } end # Document other collection_actions (excluding :create) as POSTs collection.collection_actions&.each do |action, config| next if action == :create operations["post_#{action}"] = { "summary" => "Invoke #{action.to_s.titleize} on #{collection_name}", "description" => "Perform the #{action} action on the #{collection_name} collection.", "requestBody" => { "required" => true, "content" => { "application/json" => { "schema" => { "type" => "object", "required" => ["action"], "properties" => { "action" => { "type" => "string", "enum" => [action.to_s], "description" => "Name of the collection action" }, # Optionally add custom params from config if needed } } } } }, "responses" => { "200" => {"description" => "Action performed successfully"}, "400" => {"description" => "Bad Request - Invalid action or parameters"}, "401" => {"description" => "Unauthorized"}, "403" => {"description" => "Forbidden"}, "422" => {"description" => "Action cannot be performed"} }, "tags" => [collection_name.to_s.titleize] } end

Do we need to special case create there or can we treat it like all of the other collection actions?

Yes @agrare, We can handle create the same way as the other collection actions

Fryguy · 2025-09-15T13:41:51Z

This is an awesome PR @dhamo-ror. Thank you!

Can you add the generated openapi.yml to this PR as well, which is the result of running these updates? That way we can also see the final result.

Also, not necessarily for this PR, but in the future we also need OPTIONS support for the endpoints, and we need to also add the /api endpoint itself, which is details about the server and the logged in user itself.

dhamo-ror · 2025-09-15T15:13:34Z

Thanks @Fryguy for your review. I’ll address the comments, update the PR and share the YAML file as well. I also plan to include all actions and endpoints in this, so please share your inputs if I’ve missed anything.

dhamo-ror · 2025-09-18T13:55:40Z

Hi @Fryguy, I’m attaching the JSON file generated for the API. Please take a look and share your feedback.

openapi.json

Fryguy · 2025-09-18T14:32:24Z

@dhamo-ror It should just be a part of this PR is what I mean. We have the results of running the generator in https://github.com/ManageIQ/manageiq-api/blob/master/config/openapi.json

dhamo-ror · 2025-09-18T14:55:10Z

Understood @Fryguy, Once we finalize the generator.rb file I'll run that and commit that in this PR

[email protected] and others added 4 commits September 13, 2025 05:19

Add Paths in OpenAPI generator

3706e6c

Fix Indentation

24606c3

Fix Indentation

11e960f

Fix Indentation

ce9fece

dhamo-ror requested a review from bdunne as a code owner September 13, 2025 05:46

agrare reviewed Sep 15, 2025

View reviewed changes

Fryguy assigned agrare and Fryguy Sep 15, 2025

Fryguy reviewed Sep 15, 2025

View reviewed changes

agrare reviewed Sep 15, 2025

View reviewed changes

Fryguy reviewed Sep 15, 2025

View reviewed changes

lib/manageiq/api/open_api/generator.rb Show resolved Hide resolved

agrare reviewed Sep 15, 2025

View reviewed changes

Fryguy reviewed Sep 15, 2025

View reviewed changes

agrare reviewed Sep 15, 2025

View reviewed changes

Fryguy reviewed Sep 15, 2025

View reviewed changes

agrare reviewed Sep 15, 2025

View reviewed changes

agrare added the enhancement label Sep 15, 2025

dhamo-ror added 2 commits September 18, 2025 13:30

Minor Style changes

773de18

Minor Method change

dc405f6

	"subcount" => {"type" => "integer", "description" => "Number of resources returned"},
	"subcount" => {"type" => "integer", "description" => "Number of resources returned after filters applied"},

	"count" => {"type" => "integer", "description" => "Total number of resources"},
	"count" => {"type" => "integer", "description" => "Total number of resources without filters applied"},

		collection.respond_to?(:collection_actions) &&
		collection.collection_actions&.key?(action)

		collection.respond_to?(:resource_actions) &&
		collection.resource_actions&.key?(action)

	properties.each { \|_, prop\| prop.delete("required") if prop.is_a?(Hash) }
	properties.each_value { \|prop\| prop.delete("required") if prop.is_a?(Hash) }

Add Paths in OpenAPI generator #1297

Are you sure you want to change the base?

Add Paths in OpenAPI generator #1297

Uh oh!

Conversation

dhamo-ror commented Sep 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dhamo-ror Sep 19, 2025 • edited by Fryguy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fryguy commented Sep 15, 2025

Uh oh!

dhamo-ror commented Sep 15, 2025

Uh oh!

dhamo-ror commented Sep 18, 2025

Uh oh!

Fryguy commented Sep 18, 2025

Uh oh!

dhamo-ror commented Sep 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dhamo-ror Sep 19, 2025 •

edited by Fryguy

Loading