Load PathItemObject from external resource (a.k.a. self-describing resources, is this possible?)

[tknerr]

Currently I maintain the specification of my REST service in the hand-written swagger .yaml format.

I'm wondering whether it would be possible to put the swagger compliant description of the resource (a PathItemObject that would be I guess) right into the resource itself => so the resource is self-describing and the documentation right beside the code.

E.g. http://acme.com/v1/users/1?describe returns the swagger json PathItemObject to describe itself.

[webron]

Someone has suggested it before, and said they may be working on a library that will do something similar.

The main problem is that it will give you documentation for that endpoint only, and you'd still need to include the additional model definitions, security, base path and so on.

So possible? Probably. Useful? Not sure.

[tknerr]

Thanks @webron for the feedback.

Actually I was thinking (but didn't describe it properly ;-)) of having a central / global swagger .yaml which defines the basepath, maybe model definitions too, but has the ability to link to another URL (e.g. http://acme.com/v1/users/1?describe) for retrieving the PathItemObject details.

I believe I had seen that once in a v1.0 .yaml example, but not sure where that was...

[webron]

Just remember that yaml is not the language of the spec, but json is.

You can use $ref's (though there's currently an issue with it) to link to external docs.

But based on your use case, I don't really see what you're trying to achieve. Why just not have the application generate the spec altogether (as many do)?

[tknerr]

Thanks @webron for the suggestions. I think generating the specs would be the proper way to go. However, I don't have a real application, just a few cgi-based legacy HTTP GET services that I want to document with swagger.

So I played around with $ref, but couldn't get it working properly. Here is what I tried:

in my main swagger json:

...
    "paths": {
        "/foo": {
                "$ref": "http://acme.com/foo.json"
        },
        "/users": {
            "get": {
                ...
            }
...

in the external foo.json:

{
    "get": {
        "summary": "summary of foo",
        "description": "foo description",
        "responses": {
            "200": {
                "description": "An array of Foos",
                "schema": {
                    "type": "array",
                    "items": {
                        "Foo": {
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "description": "the id of foo."
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

...but I couldn't get it to work yet, the error message in the js console while loading swagger-ui indicated that it couldn't load the external resource ("Uncaught TypeError: Cannot read property 'length' of undefined").

I had tried several variations of specifying the external foo.json (it is on the same host), including foo.json, #foo.json and the full path http://acme.com/foo.json but all produced the same error. So I guess the format or the way I'm trying to use the $ref must be wrong...

[webron]

Right, the spec doesn't allow $ref in that location. We do have an issue with the $ref for path/operation definitions which I hope to resolve soon.

[tknerr]

Ah ok, I thought that $refs actually would be supported there because after you mentioned it looked at the spec again and found $ref mentioned here ;-)
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject

Anyway, I guess I'm not on latest state from master with swagger-ui either... It would be awesome if you could ping me here once the issue is solved, then I could give it another try.

Btw: It's not urgent or critical for me right now, so no need to hurry

[webron]

My apologies. I've misread your sample, and yes, it should be supported in general (it's probably not supported by the UI yet).

[webron]

@tknerr - first, I retract my comment regarding the YAML not being a first class citizen - it is.

Second, do we still have any action items here or can we close this issue?

[tknerr]

@webron didn't have the time to try it out yet, but it seems to be possible looking at @mission-liao's pull request:
https://github.com/mission-liao/pyswagger/pull/21/files#diff-5fe6828151d09e04cd5d6c2d48a67348R15

I'm fine with closing

[tknerr]

/cc @fleque might be interesting for you