Is this doc still relevant?

Question

Is this doc still relevant?

lasomethingsomething opened this issue 8 years ago · 7 comments

lasomethingsomething commented 8 years ago

https://github.com/zalando/api-first-hand/blob/master/docs/REFERENCES.md

Asking because the main README has this:

If not, we can delete it.

Answer 1 · 2017-03-13T07:18:30.000Z

The REFERENCES is in-depth explanation how we work with json references in the plugin's source code. This is supposed to be useful for plugin developers as opposed to the plugin uses, for which is the section in the README

Answer 2 · 2017-03-13T11:38:25.000Z

Thanks, @slavaschmidt! This sentence is a little confusing: "A $ref element of the specification is allowed to contain a name of file as its part." As its part of what, exactly? And "a name of file" means ... can we be a bit more specific?

Answer 3 · 2017-03-13T11:39:43.000Z

Also this sentence: "It is also possible to reference a definition in one specification from another specification." [rewrite as?] => "You can reference a definition in one specification across other specifications."

Answer 4 · 2017-03-13T13:02:15.000Z

This sentence is a little confusing: "A $ref element of the specification is allowed to contain a name of file as its part." As its part of what, exactly? And "a name of file" means ... can we be a bit more specific?

It basically means, you can use filename to reference part of another specification.

Answer 5 · 2017-03-13T13:09:06.000Z

Does this make sense to you, @slavaschmidt?

You can use a filename to reference part of another specification with the $ref element. You can split a single specification into multiple files (as shown in cross_spec_references.yaml). You can also reference a definition in one specification across other specifications.

Answer 6 · 2017-03-13T13:10:38.000Z

Totally. For example one can create domain_model.yaml and then reference it from any other API specification

Answer 7 · 2017-03-13T13:12:17.000Z

Awesome, thank you @slavaschmidt!