Swagger missing schema(s)

[robot-ranger]

I thought i was being super clever using https://github.com/swagger-api/swagger-codegen to generate a python client from swagger provided by cppagent.

Unfortunately it is all but useless without schemas in the response definitions within swagger.json because the generated code expects a response type of None. (due to there being no schema specified; from swagger's perspective there is no response)

Adding the entirety of the mtconnect model is probably too big of a lift; could we add some high level schema defs?
Parsing the content could be left to the client implementation for now...

Maybe we just add high level schemas for the following:
MTConnectDevices/Header/Devices
MTConnectStreams/Header/Streams
MTConnectError/Header/Errors

...and the content inside [Devices,Streams,Errors] is just str type?

This would at min allow for swagger-codegen clients to function albeit leave actual content parsing and validation to the client implementation?

Any thoughts?

[wsobel]

I'm open to that and had the same issue you ran into, the MTConnect model was too big to specify in swagger, so I punted. If you have something that works and want to contribute, I'd be happy to add it to the agent swagger response.

The internal model representation in the entity factory definitions could generate some documents. I have not looked into this, but that may be another direction we could explore.

[robot-ranger]

Oh man. the whole mtconnect standard in swagger would be so nice. but I dont think that is very practical 🤣

However, i do think we could start high level and iteratively develop "downward". I think the topest surface level would at least enable a swagger client to function. But this is a rabbit hole and we would need to constrain our efforts to some depth.

Header is common to all response docs and small. that seems trivial to schema-tize. I think that makes all 3 response types relatively simple, lets just start by making the "content body" a string. the client is responsible for parsing, validation, etc. (for now)

Devices doc (ie /probe):

{
    "type": "array",
    "items": {
        "MTConnectDevices": {
            "type": "object",
            "properties": {
                "Header": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Header"
                    }
                },
                "Devices": {
                    "type": "string"
                }
            }
        }
    }
}

Streams doc (ie /current or /stream:

{
        "type":"object",
        "items": {
            "MTConnectStreams": {
                "type": "object",
                "properties": {
                    "Header": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/Header"
                        }
                    },
                    "Streams": {
                        "type": "string"
                    }
                }
            }
        }
    }

Errors doc ( ie - bad url parameter, no device with that uuid, sequence out of bounds, etc):

{
        "type": "object",
        "items": {
            "MTConnectErrors": {
                "type": "object",
                "properties": {
                    "Header": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/Header"
                        }
                    },
                    "Errors": {
                        "type": "string"
                    }
                }
            }
        }
    }

[robot-ranger]

maybe i am out of my depth here... can we just tell swagger to expect a return of json or xml in its entirety?

[wsobel]

We may, I'm not a swagger expert myself. If you find out, I can do that as well.

[robot-ranger]

Got it!

I was way over complicating it

It looks like responses just need to have "content" included. then swagger client assigns a response_type of str during generation and simply returns the string response.

We need to add "content" to each response definition:

"responses": {
  "200": {
    "description": "OK",
      "content":{
	  "application/json":{
              "schema":{
	          "type":"string"
          }
      }
    }
  }
}

i believe this is the minimum required for a functional swagger client

[robot-ranger]

a little more testing. the following will allow for the swagger client to select between json and xml respose:

"responses": {
	"200": {
		"description": "OK",
		"content": {
			"application/json": {
				"schema": {
					"type": "string"
				}
			},
			"application/xml": {
				"schema": {
					"type": "string"
				}
			}
		}
	}
}

I can see where artifacts of swagger.json are constructed

cppagent/src/mtconnect/sink/rest_sink/server.cpp

Line 320 in be0d0c3

// Swagger stuff

...but i cant follow it well enough to add this myself - ill poke my dev and see if he can help