feat(apib): add format link

[marcofriso]

Closes APIARY-6103

[kylef]

One caveat here is that if the underlying parser added any other meta or attributes they would go missing. It might be a bit simpler to construct a minim elements from the given result. In options there is namespace which can be used as a minim namespace. You can get hold of a ParseResult element instance in the same way that the other parsers work. Returning a ParseResult here does not change the behaviour, the API Elements Core logic detects if the returned value is a Minim element, in the cases it is not, it will convert it to be one (thus doing what you'd be doing here).

const { namespace } = options;
const parseResult = namespace.fromRefract(source);
.. new namespace.elements.Link(...);
return parseResult;

What do you think?

[marcofriso]

@kylef in options there is not namespace, I don't know how to access it here. Seems to me that API Elements are managed internally by the drafter function, so by Protagonist.

[kylef]

The options passed into the function:

function parse({
  source, generateSourceMap, generateMessageBody, generateMessageBodySchema,
  requireBlueprintName,
}) {

can be adjusted to add namespace. It doesn't need to be added to the options passed to drafter.

[marcofriso]

changed

[kylef]

Suggested change

	link.title = 'Apiary Blueprint';
	link.title = 'API Blueprint';

This is the API Blueprint adapter

[marcofriso]

changed

[kylef]

Can you please explain the intent of this check? I am not sure it is needed.

[marcofriso]

In case of error it does not add the format link, do you want to remove it?

[kylef]

I think in all cases we should include the link element, some editors such as Apiary show the source format on annotations which the link element's title will be useful for:

The use-case may be finding the underlying format which caused the error. The "Unknown" here would become "OpenAPI" etc.

[marcofriso]

removed condition e310ea3