Open kylef opened 6 years ago
This could simplify Dredd as well. Currently its parse
function returns two results, the media type and the API Elements object. As Dredd needs to know the media type in multiple occasions later on, it's a bit tedious to keep the information together in the rest of the flow. If it's in one package out of the box, that would be nice.
And yes, I know one of the occasions is a dirty "if/else media type" branching, which is something beating the purpose of API Elements, but it's there for backward compatibility. Although scheduled to be removed, it's gonna live with us for a while. Theoretical purity meets reality 🙂
Yes I think this has been discussed in the past. We need to embed the meta information from the original document inside the api elements it self. It creates a lot of problems and bypasses currently.
What the new doc renderer needs is:
I think it would make sense that we provide information in the parse result (or API Element) that contains some information about the source document such as the format itself (Swagger, OpenAPI, API Blueprint) and the version of that format.
Although the goal of API Elements is that the format is canonical and the original source shouldn't matter. When telling users about the errors/warnings or linking to the underlying specification it can be needed. I believe Apiary editor for example tells the user the format used in the error/warning messages so it has to detect this itself.
I think this should be in form of a link element in the parse result to the specific format/version, the link element can contain a title. I am not entirely sure what link relation we should use, I've used
via
in the example, we should ensure that is semantically correct.For example:
This could perhaps look something like: