Composite spec shall not hard code the base paths for child specs. about azure-rest-api-specs HOT 10 CLOSED

@lmazuel let's just go with what you have for the time being and bring this up in the next design discussion.

/cc @sphibbs

from azure-rest-api-specs.

@amarzavery

from azure-rest-api-specs.

I like this idea. Those should all be relative paths.

from azure-rest-api-specs.

I am not sure if that is a good idea. I may be having swagger specs at two different locations that are not relative to a common base folder. With absolute paths, you can still compose them.

This is a low hanging fruit among all the items that we need to solve.

from azure-rest-api-specs.

If multiple spec files are not organized in a way that it's 'common' to something, i.e. the common base path, then is it a good idea to proceed the composition without checking?

For example, we want to composite the Compute client family (Compute\VM, Compute\VMSS...), but it's hardly likely to composite Compute with Storage RP clients?

from azure-rest-api-specs.

any update?

from azure-rest-api-specs.

@devigned @amarzavery
By changing this PR to use relative from the repo root, now it's working:
#359

By what do you think makes more sense? Change regarding to the repo root, or the composite file folder?

from azure-rest-api-specs.

@amarzavery is OOF for a bit.

I think the issue we had before was that there is no real idea of root without the entire directory structure. Basically, with absolute URIs, the composite document can stand on it's own.

I like the relative URI's. I think following JSON Reference would make the most sense. Thoughts?

from azure-rest-api-specs.

@devigned For what I see, JSON reference is too much complicated for our needs here. We don't need the ability to point inside the document with an anchor. But they give a recommendation about the relative uri solving:

If the URI contained in the JSON Reference value is a relative URI, then the base URI resolution MUST be calculated according to [RFC3986], section 5.2. Resolution is performed relative to the referring document.

According to this, the right relative path is regarding the place of the composite file.
Then the composite for Compute should be:

{
  "info": {
    "title": "ComputeManagementClient",
    "description": "Composite Swagger for Compute Client"
  },
  "documents": [
    "./2016-03-30/swagger/compute.json",
    "./2016-03-30/swagger/containerService.json"
  ]
}

and not

{
  "info": {
    "title": "ComputeManagementClient",
    "description": "Composite Swagger for Compute Client"
  },
  "documents": [
    "./arm-compute/2016-03-30/swagger/compute.json",
    "./arm-compute/2016-03-30/swagger/containerService.json"
  ]
}

Agree? If you agree, it will be better to block #359 until I made the update in the script and they push a new commit with the right version.

from azure-rest-api-specs.

This has been done last year.

from azure-rest-api-specs.