Foreman-rake apipie:static_swagger_json not showing the response schema

Hi,
this is my first post but i hope i’ll get an answer to my problem.
I’m writing a central middle-ware solution which should use the OpenAPI V 3.0 standard.
The API is quite extensive so i tried to export the API to swagger JSON format.
It works, but the valid response items are missing.
I found the RABL files, but would love to save hours by parsing the RABL files and convert it to JSON.
E.g. /tasks/{id} Swagger output

"/tasks/{id}": {
      "get": {
        "tags": [
          "foreman_tasks"
        ],
        "consumes": [
          "application/x-www-form-urlencoded",
          "multipart/form-data"
        ],
        "operationId": "get_tasks_id",
        "summary": "Show task details",
        "parameters": [
          {
            "name": "id",
            "type": "string",
            "in": "path",
            "required": true,
            "description": "UUID of the task"
          },
          {
            "name": "location_id",
            "type": "number",
            "in": "query",
            "description": "Set the current location context for the request"
          },
          {
            "name": "organization_id",
            "type": "number",
            "in": "query",
            "description": "Set the current organization context for the request"
          }
        ],
        "responses": {
          "200": {
            "description": "ok"
          }
        },
        "description": ""
      }
    }

What is missing is the response item format. Like:

"content": {
 "application/json": {
  "schema": {
    "type": "object",
    "properties": {
      "pets": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}

Please give some advice how i can get the valid response objects using the rake api swagger export.
Any help would be greatly appreciated !

Greets

Franz

1 Like

@ofedoren any pointers? FTR apipie-rails is a standalone project, you could probably open an issue at GitHub - Apipie/apipie-rails: Ruby on Rails API documentation tool

Hi Mark,
thanks for the hint !
I found an open issue to a feature request regarding OpenAPI 3.0 export.
Feature request: Export to OpenAPI 3.0 #713
Will update the feature request accordingly !

Thx.
Franz

2 Likes

Hi Marek,
i found my answer in the Readme.rst file of the current apipie sources (github).

Known limitations of the current implementation

  • There is currently no way to document the structure and content-type of the data returned from a method
  • Recorded examples are currently not included in the generated swagger file
  • The apipie formats value is ignored.
  • It is not possible to specify the “consumed” content type on a per-method basis
  • It is not possible to leverage all of the parameter type/format capabilities of swagger
  • Only OpenAPI 2.0 is supported
  • Responses are defined inline and not as a $ref

Since the thread mentioned above didn’t raise much attention, i’ll only translate the api calls i need for my project.
I want to point out, that generating swagger output is quite common nowadays, so perhaps the feature request will catch a core developers eye ,-)

Rgds.
Franz

2 Likes

I agree it would be nice, however migrating off apipie to something else would be a lot of effort and I can’t really judge how much work it would be to implement this in apipie. Our main use case is for generating bindings for the CLI.

Hi Marek,
i meant the apipie core developers.
Anyhow, thank for the great work on Foreman !

Rgds.
Franz

I’d say that foreman-ansible-modules is also a big use case today and we also have a Python library to wrap it:

This is in addition to the Ruby bindings which have existed for a much longer time: