3

I have my yaml files split up according to a structure like this:

.
├── index.yaml
├── info
│   └── index.yaml
├── definitions
│   └── index.yaml
│   └── User.yaml
└── paths
    ├── index.yaml
    ├── bar.yaml
    └── foo.yaml

index.yaml:

swagger: '2.0'
info:
  $ref: ./info/index.yaml
paths:
  $ref: ./paths/index.yaml
definitions:
  $ref: ./definitions/index.yaml

info/index.yaml:

version: 1.0.0
title: Service API

definitions/index.yaml

User:
  $ref: ./User.yaml

definitions/User.yaml

type: object
properties:
  name:
    type: string

...and so on (but you get the idea). I followed the guidance of a blog post that did exactly this. So before calling initializeMiddleware from the swagger-tools library, my understanding is that I need to merge all these yaml files into a single file. I tried doing that the way @mohsen____ describes in his blog, leveraging the json-refs library and calling the resolveRefs (or resolveRefsAt) function to get a promise-ified response object that contains a version of the document with the JSON references resolved. This doesn't seem to work though. When I try the following nothing gets logged to the console:

let options = {
    filter: ['relative', 'remote']
};

jsonRefs.resolveRefsAt('./swagger/index.yaml', options)
.then(function (res): any {
  console.dir(res);
  console.log(JSON.stringify(res.resolved, null, 2));
}, (err) => {
  console.error(err);
});
Community
  • 1
  • 1
TovrikTheThird
  • 471
  • 2
  • 7
  • 20
  • @Anthon I modified my question slightly but all the information should be there already. Basically, I have a yaml file that is structured properly. I call `jsonRefs.resolveRefsAt()` on the file and expect to see a log to the console of the file with all the references resolved but I don't see that (and see nothing instead). – TovrikTheThird Apr 25 '17 at 20:05
  • Just FYI, your `index.yaml` is not a valid OpenAPI/Swagger 2.0 spec. The blog claims "Swagger spec can use `$ref`s anywhere in the spec" - that's actually [not correct](https://github.com/swagger-api/swagger-parser/issues/147#issuecomment-246847871). `$ref` is only allowed in some places - search the [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) for `Reference Object` and `$ref` and also see [Reuse Philosophy](https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/REUSE.md). – Helen Apr 25 '17 at 20:14
  • When `$ref`s are used correctly, tools like Swagger UI can/should be able to resolve the references in the main file automatically, without having to merge the files. – Helen Apr 25 '17 at 20:19
  • @Helen OK this is great. Sounds like the error is with my use of `$ref`s and not my use of the `json-refs` library. That being said, that was what I first looked at (to see if my structure was incorrect in some way), and I was unable to find anything that looked like I was misusing the `$ref` tag – TovrikTheThird Apr 25 '17 at 20:28
  • @Helen Missed your inclusion of the Reuse Philosophy the first time I read through that. I think that will definitely help me find my problem Thanks very much, will post back if I still can't find it. – TovrikTheThird Apr 25 '17 at 20:32
  • Here's an example that shows almost all allowed usages of external `$ref`s: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/petstore-separate/spec/swagger.yaml – Helen Apr 25 '17 at 20:38
  • @Helen what function exactly is dereferencing all these relative paths? Currently I call `yaml.safeLoad(fs.readFileSync(swaggerPath, 'utf8'));` and pass that into `swagger.initializeMiddleware(swaggerDefinition, (middleware) => {});` – TovrikTheThird Apr 25 '17 at 21:53
  • I'm not familiar with swagger-tools, sorry. This is usually handled by a tool's Swagger parser, e.g. in the [Swagger Editor](http://editor.swagger.io) this is done by [swagger-js](https://github.com/swagger-api/swagger-js). – Helen Apr 27 '17 at 19:26

0 Answers0