Allow fragment edition for REUSE usage

[danielm64]

The REUSE philosophy relies on YAML fragments for:
•Operations
•Parameters
•Responses
•Models

Editing these fragments is not supported by swagger-editor.
Currently, we write full swagger 2.0 specs, and, when complete and valid, comment all what should not be in the fragment...
would appreciate this support to suppress the unnecessary work...

[mohsen1]

I understand what the requirement is but I don't know how this should be implemented. Problem is, it's impossible to tell if you're writing a fragment or the Swagger spec is just invalid.

@webron Does Swagger have a method for marking fragment files? Something like specifically formatted comments maybe?

[webron]

That's a fair question, but the answer is no. Eventually, it's just YAML/JSON files. The 'root' file, representing the Swagger object, has a specific structure (as you know), but the fragments can pretty much be anything.

That means that the validation could be done only from the root file, as that's the only time you can assign a meaning to the referenced objects. And yes, that makes auto-complete and so on more complicated. I can possibly think of a few ways to ease up the implementation (in terms of user experience), but perhaps we should discuss that separately? May be easier.

[mohsen1]

For Swagger Editor to support this we can have to have some specific comments. Here is my proposal for the spec of the comments I that indicates a YAML file is a partial swagger file:

1. First line MUST be a comment

2. Comment body is formatted as follows and containing # partial-swagger: (space, partial-swagger, colon, space)

   # partial-swagger: {{path}}

3. the path component can be a string or a JavaScript array.

4. If path is string it is pointing to a root object in swagger document.

   Example:

   # partial-swagger: info
   title: My API
   description: An API

5. If path is an array it is pointing to an object deep inside the swagger document. It should be valid JavaScript(or JSON) array
   Example:

   # partial-swagger: ["info", "contact"]
   email: me@example.com
   url: example.com
   name: My Name

Obviously this is not part of Swagger spec and it's here only to help Swagger Editor work with partial YAMLs that build up a larger spec.

@webron @fehguy Please review

[danielm64]

Hi,

No news...
@webron @fehguy can you please review @mohsen1 proposal ?

Thanks.

[fehguy]

@mohsen1 does this mean you're suggesting support of non-swagger spec files inside the editor, by using the comment as the indicator?

[mohsen1]

Yes, there is no way to know if Swagger is invalid or it's just a part of a larger spec.

[webron]

The comments way is probably the only way to go due to obvious limitations.

A few questions/comments:

• Can you please clarify the example of the array? I'm not sure I understand what you mean by it.
• Are you going to perform partial validation on those segments?
• This kind of implementation forces a structure of the segments. I don't mind it, though some people may expect something slightly different. We can try breaking it down further and see if/how we'd want to support more cases. I'm okay with basic support at first.

[mohsen1]

Can you please clarify the example of the array? I'm not sure I understand what you mean by it.

The array is a made up format for "path" to this partial from root of the spec. I guess we're better off using JSON Pointer (RFC 6901) for that.

Are you going to perform partial validation on those segments?

My thinking is to fill in the missing parts with minimal swagger and validate the whole thing. It would be a lot of work to support partial validation in swagger-tools

This kind of implementation forces a structure of the segments. I don't mind it, though some people may expect something slightly different. We can try breaking it down further and see if/how we'd want to support more cases. I'm okay with basic support at first.

I can't think of anything other than breaking down swagger into smaller files that are pieces of a larger spec. I would love to see different ways of doing it though...

[webron]

Oh, so by this example:

# partial-swagger: ["info", "contact"]
email: me@example.com
url: example.com
name: My Name

You meant Contact object under Info? (I'm ignoring that this is not really a 'reuse' use case)

---

I believe partial validation is going to be requested as soon as there's ability to split files. If there's not going to be partial validation, I'm not sure there's a reason for the first-line comment (other than saying it shouldn't be validated at all, but you don't need to define the 'path' in it).

---

To clarify, it's technically possible to have something like (and forgive my json):

{
  "mypersonaldefs": {
    "modelX": {
      "type": "object"
    }
  }
}

and $ref'ing it from the root Swagger as /path/to/file#/mypersonaldefs/modelX. However, it's not really 'definitions' and it's not really a single definition in that file. We may say initially that we don't support this use case, but it's technically feasible.

---

And on that note, how will the multi-files be referenced each other? What would be the path?

[mohsen1]

Because editor is not owning the spec in it's host, there is no way to resolve relative and fragments paths. the only ref we can resolve is absolute refs

[webron]

Okay, I have a couple of thoughts on resolving relative fragments as well, but that can be phase 2. What about the other points? :)

[glen-84]

and $ref'ing it from the root Swagger as /path/to/file#/mypersonaldefs/modelX. However, it's not really 'definitions' and it's not really a single definition in that file.

This is what we're doing, FWIW. Well, the model definition file (with one or more definitions) is referenced from an operation file, which is then referenced from the main file.

We don't have the mypersonaldefs container key though.