how to split swagger.json into separate files

[eloui...@gmail.com]

Hi, I would like to use $ref to point to a file located in the same local directory, using a relative link. My swagger.json is getting really large and difficult to navigate. It would be much better if I could split it out into different files. For example, perhaps I could put my object definitions into separate files, using $ref. The specification mentions that this is possible, but nowhere can I find an example of the syntax for this. I guess I can just do some trial and error if no one replies.

Thanks,

Emily

[Ron]

You can split everything in the spec, possibly specific parts.

Where did you see in the specification that it mentions that it is possible? I may be able to guide from there.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[eloui...@gmail.com]

Hi thank you. If you go to the spec and start reading from the top, it says at the very beginning:

File Structure

The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.

By convention, the Swagger specification file is named swagger.json.

Then, if you do a find and search for $ref, it is also mentioned as a possibility for a "Path Object", here is the excerpt

$ref

string

Allows for an external definition of this path item. The referenced structure MUST be in the format of a Path Item Object. If there are conflicts between the referenced definition and this Path Item's definition, the behavior is undefined.

Unfortunately, while it states the possibility, it does not mention exactly how and I have not found any examples online of how it would look, everything I have seen appears to be inline references, #/definititions/<name>

Thanks for your help, it would make my project a lot more navigable. My main idea at present is to move all of the object definitions into separate files and reference them in some fashion using the $ref property inside of the operation definition, where it can be a request parameter or a response parameter.

Thanks!

Emily

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron]

Well, a full reference would by in the format of a URL and if you refer to a given object in it, it would have a similar definition to the one you stated.

You actually have a sample of it here:
https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#L32

which points to https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json.

In your case, you may have a definitions.json:

{

  "definitions" : {

    "sample" : {...}
  }
}

and if you want to refer to the "sample" model, you would have something like:

"$ref": "http://host/path/to/definitions.json#/definitions/sample"

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[eloui...@gmail.com]

That makes sense and I have seen references to URIs, which seems to indeed work great. However, what about the situation where the file does not live on the WWW and instead it is within the swagger-ui GitHub repo, along with the swagger.json file? What is the syntax for that. I assume it must be possible, since swagger-ui seems quite able to locate the swagger.json file. (We are using GitHub Pages and local Jekyll builds.) Thanks so much for any assistance.

Best Regards,

Emily

[Ron]

Since you're hosting with github pages, you will have a URL just like any hosted file and you should use that.

[tony tam]

Well this is trickier, Ron.  Github won't let the swagger-ui read the remote file because of CORS and content-type settings.  For example, this is a valid swagger description:

https://raw.githubusercontent.com/swagger-api/swagger-spec/master/fixtures/v2.0/json/resources/securityExample.json

However you can't put that in the swagger-ui's URL field.  You'll get lots of nasty errors.

With the new swagger-client for 2.0 spec, though, you can do this as follows:

1) Create a javascript file, assigning your swagger spec to a variable:

Filename:

your-spec.js

Contents:

var spec = { .... /* your swagger JSON spec */ .... }

2) Include your spec in the HTML:

<script src='https://raw.githubusercontent.com/your-repo/your-spec.js' type='text/javascript'></script>

3) Pass the spec variable from step 1 into the swagger UI:

  <script type="text/javascript">
    $(function () {
      window.swaggerUi = new SwaggerUi({
      url: "http://localhost:8002/api/api-docs",
      dom_id: "swagger-ui-container",
      spec: spec,
      supportedSubmitMethods: ['get', 'post', 'put', 'delete'],

Then it'll load the spec directly from github.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[eloui...@gmail.com]

All right, thanks Tony. Interesting. I will look into this and see if I can get it to work. Thanks!

Emily

[Bailey Smith]

Sorry to bring this back from the dead, but I'm working with development, staging and production environments, so I'd love to get  $ref to work with relative paths for the definitions at least. Emily, did you find a solution that worked for you? 

[lucien combe]

The documentation on the official web site is poor, as you are not the only one wondering for this. They don't give explicit example. 

Any help please ?

[tony tam]

Lucien, please explain more what you’re trying to do.  The question is poor as well :)

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[lucien combe]

On Friday, 15 April 2016 11:25:29 UTC+1, lucien combe wrote:

Hello Tony, 

You are right sorry. I am a new Swagger user and i am trying to became a champion :) .

Actually, i am describing my API using YAML. To be able to re use models i split files using the structure below :

• api/commons/
  
• definitions.yaml
• api/myApi_1/
  
• swagger-my_Api_1.yaml
• api/myApi_1/
  
• swagger-my_Api_1.yaml

Hence, in my  swagger-my_Api_1.yaml and  swagger-my_Api_1.yaml i got some $ref like '../commons/defintions.yaml#/MyModel' .

This works like a charm.

Now, i need to have a JSON version of each file. Here come problems, as i am not able to make reference to external files.

• It doesn't work with URL reference too. This solution breaks my directory structure logic anyway.
  
• I am not able to find a complete example of JSON external references to be able to check mine.
  
• When using external models, do i have to use the definitions markup ? (I do not while using YAML and it works)
• Is relative path working using JSON ?
• I am using Swagger 2.0

Thanks for your help

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[tony tam]

Hi, you can certainly use references to other files, relative or absolute are supported.  Any place you see a $ref supported in the spec, you can use them.

The references can be to YAML or JSON structured files.  It should be trivial to split your definition up using those constructs.  I suggest you look at the specification itself:

https://github.com/OAI/OpenAPI-Specification

Or samples in the specification repository.

Tony

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Francesco Bianco]

I suggest you use a command-line tool to build a composed YAML file that uses a $include tag like this https://github.com/javanile/yamlinc

Consider a group of YAML file as a subproject and compose it like gulp-concat compose multiple JS files.

$ref is more restricted for large project (It is only my opinion)