Support for multiple file references

[Petah]

Does this support cross file references?

I have a yaml file with that looks like:

definitions:
  Order:
    $ref: order.yml

But it seems to just literally link to that file, rather than importing it into the spec.

[nknapp]

Hi and sorry, this is not supported yet. The link to the file is a compromise (not a very good one, I have to admit). For now, you could use expand-swagger-refs to inline the references. I have not used it myself, but @asieira mentioned it in #19. I don't know, if it supports YAML, though.

The question is: What would you expect to happen?

1. Display referenced content as if it were defined in the main file?
2. Create a HTML from each file and create the correct links between them?
3. Something else?

[Petah]

I expected it to display referenced content as if it were defined in the main file. I should be able to work around this using expand-swagger-refs, even if i need to convert to json first.

Thanks :)

[nknapp]

I'll see if I can build expand-swagger-refs into the preprocessor. I don't know how it behaves with cycles in the ref-structure. Cycles were one reasons why inner refs are not expanded automatically. The first project I was using swagger (or json-schema) for, could, in principal, be endlessly nested, so resolving all references would not be possible. Thus, creating links to the target ref seemed more appropriate.

I'll think about it on Wednesday...

[Petah]

Any updates?

[nknapp]

No, not really. Sadly, I have not had enough time in the last weeks and when I have time, there were other things that seemed to be more important to me (and to be honest, more interesting). I will gladly accept a pull-request, probably after a short round of discussions and corrections, but to be honest, I doubt that I will find time to work on it within the next weeks, but I might find time to comment and acccept a PR.

[Maykonn]

Any updates?

[nknapp]

No, I think I would proceed to solve some of the issue, if there were more active developers on this project. Up to now, there are only occasional pull-requests (which I am very grateful for). But this is my free-time and there are so many things to do. As long as I am the only one developing here, this is just not enough fun... It would be nice, if there was at least one other person for mutual code reviews and discussions.

[Maykonn]

I understand. I solve this problem with json-refs. Below, I describe the process that I follow to solve $refs and generate a valid json or yaml file and the HTML documentation based on this files, to future visitors =D :

1. Run the following commands to install the necessary tools:

   npm install -g bootprint
   npm install -g bootprint-openapi
   npm install -g json-refs

Bootprint Bootprint for OpenAPI JSON-Refs

2. Run the following command to solve $refs:

   json-refs resolve -I relative -I remote some-path/example/index.yaml > some-path/example/html/index.json

3. Run the following command to generate the HTML documentation:

   bootprint openapi path/example/html/index.json path/example/html/

The html will be generated at path/example/html/, just open the path/example/html/index.htmlon your browser.

But, you can paste or load the path/example/html/index.json on Swagger Editor too.

Additional documentation: OpenAPI.