Unable to reference external Json in 2.0 spec

[tynor88]

Spec 1.2:

{
"apiVersion": "1",
"swaggerVersion": "1.2",
"basePath": "http://localhost",
"apis": [
{
"path": "/swagger/api-docs/External", // This would return a stattic swagger spec on its, generated dynamically. It worked fine in 1.2 spec
"description": "Description"
},
]
}

Spec 2.0:

{
"swagger": "2.0",
"host": "http://localhost",
"basePath": "/",
"paths": {
"/swagger/api-docs/External": // How to return API doc here from another site???
}
}

I can see in swagger spec 1.2 the documentation for basePath was:

"The root URL serving the API. This field is important because while it is common to have the Resource Listing and API Declarations on the server providing the APIs themselves, it is not a requirement. The API specifications can be served using static files and not generated by the API server itself, so the URL for serving the API cannot always be derived from the URL serving the API specification. The value SHOULD be in the format of a URL."

This is exactly the feature im trying to accomplish with 2.0. Am i missing something, or is this feature left out?

[chasetec]

basePath has nothing to do with referencing external JSON. If the swagger file is missing host and basePath then you can assume the host the served the swagger file is the host that provides the web services. basePath is an optional part of the full url that comes between the host and the operation's path. (host + basePath + path == url).

Splitting a swagger spec into multiple files in 1.2 was about creating categories of operations. In version 2 you put everything in one file and use tagging to categorize operations.

[tynor88]

Hi @chasetec

Thanks for getting back. I think I've not clearly stated my problem. We are having several ASP.NET Web API's hosted on different sites (on the same server right now). We are using https://github.com/domaindrivendev/Swashbuckle for generating JSON spec on the fly from the Web API sites.

When using 1.2 of swagger spec, the following works fine:
https://gist.github.com/tynor88/d502e611cd3bcc7ae88f

The "path" element is pointing to another Web.API, which returns swagger spec on the fly using Swashbuckle. Swagger will in this case call this url, and get the swagger spec returned. I am trying to accomplish the same thing with 2.0 with swagger, but it seems swagger is never trying to call the website (I can see that in Fiddler).

[webron]

@tynor88 - If you're looking for a way to collect several microservices hosted on different machines into a single spec, that's something that we haven't released yet.

Otherwise, I'm not sure what's your intention.

[tynor88]

@webron But this is already working perfectly fine with Swagger 1.2 using the "apis" array in the Json. Is this not going to be supported by the 2.0 spec?

[webron]

It's going to be supported in a different way.

[tynor88]

Ok thanks for getting back. I will keep an eye for it, in the upcoming releases 👍

Is there any work item on this i can follow? Can't seem to find one.

[prashanthpatha]

Is it possible to divide operations into multiple json files in 2.0 ? If it is possible , how ? If it is not possible with 2.0 , then the only choice we have is to use 1.2 spec because there are lot of operations in multiple objects which cannot be combined into single json.

[tynor88]

This is the exact feature i am missing too. It was supported in 1.2 but it seems it is not supported yet in 2.0. @webron said earlier in this thread, that this is something that is going to be supported in a different way. Though I haven't found a work item for this yet.

[prashanthpatha]

Based on the reply by @webron ( "It's going to be supported in a different way" ) , i understand that operation grouping is done via tags in spec 2.0. But , can we group the operations in multiple json files which eases the maintenance, increases the clarity and readability and decreases the complexity of having every operation in one file ?

[webron]

I really wish I had a clear update on this issue, but unfortunately not yet. We have a plan, but we need to finalize it. I'll see what we can do in order to push it faster.

[JamesMessinger]

Some parsing libraries (such as Swagger Parser and Swagger Tools) allow external files and URLs to be referenced using $ref. For example:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Pet Store",
    "description": "This file includes $refs to external files"
  },
  "paths": {
    "/pets": {
      "get": {
        "responses": {
          "default": {
            "description": "references the pet.json file",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "pet.json"
              }
            }
          }
        }
      }
    }
  }
}

[webron]

I don't think that covers what @prashanthpatha is looking for.

[JamesMessinger]

Ah, ok. I just re-read it, and it seems to me that he's wanting to reference external files for entire operations and/or paths. Swagger Parser supports that too:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Pet Store",
    "description": "This file includes $refs to external files"
  },
  "paths": {
    "/pets": {
      "get": {
        "$ref": "getPets.json"
      },
      "post": {
        "$ref": "postPets.json"
      }
    },
    "/pets/{name}": {
      "$ref": "petByName.json"
    }
  }
}

[webron]

Again, I don't think that answers the request. It's not about splitting specific paths to different files but groups of paths to different paths. If there are 100 paths and each is described in a different file, it may be as unmaintainable as a single file.

[JamesMessinger]

hmmm.... ok then. I've got nothing. :)

[webron]

@BigstickCarpet - don't get me wrong, I appreciate the comments. Didn't mean to discourage you or anything.

[JamesMessinger]

No worries. No offense taken. You know I love you guys. :)

[prashanthpatha]

What @webron has pointed out is exactly what i am looking for. However thanks for the replies and looking forward to the future update to support it.

[tmcdonnell87]

@webron any update on microservices support you reference above? Thanks!

[webron]

@tmcdonnell87 - can you tell me what aspect of support are you looking for in your case?

[tmcdonnell87]

@webron We support a collection of services running on different servers, such as node.example.com, cxf.example.com, etc. In some cases, a service like cxf.example.com/foo might be running on a separate server than cxf.example.com/bar.

With swagger 1.2, you could have one hosted resource list that had each path as the API declaration on each server. With 2.0, I'm having trouble figuring out how that would be done, and your comment

If you're looking for a way to collect several microservices hosted on different machines into a single spec, that's something that we haven't released yet.

seemed quite promising. Though that was six months ago, and I haven't found any info about it being released.

Thanks for the quick reply!

[webron]

So, the official support for it isn't quite out there and may only be part of the next version of the spec.
However, if you want to host several listings under a single swagger-ui, that's doable. Would that suffice for now?

[tmcdonnell87]

You mean set up a proxy to combine them? Or multiple json files in the swagger ui?

[webron]

Multiple jsons in the UI. A proxy won't help in this case.

[tynor88]

@tmcdonnell87 For now we just merge the multiple specs, in to one spec ourselves. This is not elegant, but the only way to support micro services so far.

This feature worked in swagger 1.2 but unfortunately not in 2.0. I hope to see this again though in a future version of swagger-spec, as building microservices is a quite popular architecture style for larger applications.

[webron]

While I normally don't comment about the probability of a one feature or another to actually make it into the next version of the spec, I can say that in this case the odds are 100% that it makes it in.

[tynor88]

@webron Sounds good, will be looking forward to see this feature 👍

[tmcdonnell87]

Thanks @webron. Looking forward to it.

[UncleJohnsBand]

Any new status on this?

[handrews]

@webron did this feature that had 100% odds of making it in make it in to whatever release you were talking about? I confess I haven't slogged through this whole thing to figure out what that might be.

[webron]

I don't recall :(

[handrews]

@webron well if it's still important I imagine someone will eventually complain ;P