Edit external $ref yaml files

[3DRaven]

When used $ref to external file with definition:
Product:
$ref: "./extdef/Product.yaml"
I open external file in "Swagger Editor" and got errors:
object has missing required properties "info", "paths", "swagger"
object has properties "properties", "type" which are not allowed

Need to change Swagger Editor for appropriate edit external ref files and add code assist to main swagger spec for find external refs yaml files. Set property "path to external definitions" and show all yaml files in code assist.

Thanks :)

[tedepstein]

Hi @3DRaven , I am not sure I am following your scenario correctly. I'll ask some specific questions here:

When used $ref to external file with definition:

So you have this code in your Swagger/OpenAPI 2.0 top-level document, correct?

  Product:
    $ref: "./extdef/Product.yaml"

Is your top-level document (the one containing the $ref) in a project that is loaded into the Eclipse workspace? If so, the relative path ./extdef/... should normally be within that same project. Please verify.

I open external file in "Swagger Editor" and got errors:
object has missing required properties "info", "paths", "swagger"
object has properties "properties", "type" which are not allowed

How did you open that external file in the Swagger Editor? From the right-click menu, like this?

From the error messages you saw, it sounds like that "./extdef/Product.yaml" file was an OpenAPI 3.0 file, or a YAML file that was neither OpenAPI 3.0 nor 2.0 (Swagger). In that case, opening it in the Swagger Editor would show errors like those, because the Swagger Editor performs validation according to the OpenAPI 2.0 specification.

We have open issues #431 and #444 that describe problems with the recognizers ascribing the wrong file type to YAML files. This has been improved, but it's still not perfect. As a workaround, you can use the right-click menu to open your file in the correct editor, depending on what type of YAML file it is. If your file type is OpenAPI 3.0 and you don't see that option in the right-click menu, you can choose Open with > Other... and the choose OpenAPI v3 Editor from the list.

Need to change Swagger Editor for appropriate edit external ref files and add code assist to main swagger spec for find external refs yaml files. Set property "path to external definitions" and show all yaml files in code assist.

It sounds like the file containing the definition you wanted was in your project, but it might not be a valid OpenAPI v2 or v3 document. If it's not a recognized OpenAPI document, then code assist won't offer its contents in the proposal list.

If the external file is a valid OpenAPI document within the current project or workspace, you can use scope cycling to find it. Just press the code assist hotkey multiple times to cycle through:

1. Available components in the open document.
2. Available components in the current project.
3. Available components in the current workspace.

If it's not finding your file because it was improperly recognized as the wrong file type (see above), opening it in the correct editor and closing it should work around that problem.

Choosing reusable definitions from locations outside the workspace, and/or choosing from YAML and JSON files that are not OpenAPI 2.0 or 3.0 documents, is a good idea for a future release. We would like to build in these features, but we don't have a timeframe for this right now.

[3DRaven]

Hi! Thanks to answer :)

I have two files:

1. Main swagger 2 spec (example):
   swagger: "2.0"
   info:
   host: api.example.com
   paths:
   definitions:
   Example:
   $ref: './extdef/example.yaml'

2. Extracted definition file example.yaml:
   type: object
   properties:
   prop1:
   .......

So, i open file 1 and all fine but if i open file 2 in Swagger editor i get this errors.

But swagger-codegen working fine for this files.

[tedepstein]

I see. Somehow your example.yaml file has been recognized incorrectly as a Swagger 2.0 document, when it is really just a YAML document, not intended to follow the full Swagger 2.0 format.

In that case, you can correct this by opening your example.yaml file in the YEdit YAML editor:

Once you've done that, Eclipse should now recognize the file as a plain YAML file, not a Swagger file.

[3DRaven]

yes, i do. its feature request. i need to swagger editor recognize all ref definitions files and parse its correctly and then i can use autocomplete, errors recognition and other in refs files.

[tedepstein]

Hi @3DRaven . OK, I have extracted issues #491 and #492 to try to capture your suggestions here. While we don't have any specific plans to build these features at this time, it's good to have the issues open for the community to explore further and maybe submit their own implementations as pull requests.

I think #431 and #444 already describe the problems with incorrect file type recognition.

If you are OK with the way I have described your feature requests in these two new issues, please feel free to close this one.

[3DRaven]

Ok, tnx.