widdershins
widdershins copied to clipboard
Mermade
Does widdershins support Open API Extensions, like Amazon AWS API Gateway?
I'm currently using widdershins to convert an openapi-3.0 spec, into a slate/shin compatible markdown file. The cli throws the following error:
Invalid Variable Name "any+" in "{any+}"
Error: Invalid Variable Name "any+" in "{any+}"
It looks to me that the Error is being thrown because of using AWS API Gateway OpenAPI Extensions - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html like these in the spec.
Is it somehow possible for widdershins to either omit those routes in the spec, or specify how to handle them? I was trying to understand if it's possible, but I couldnt clearly identify that from the docs. It'd be great if you could point me in the right direction.
Widdershins supports specification (aka vendor) extensions fine (in that it will ignore them). What seems to be happening here is that you may have a character in your in:path parameter (+) which is confusing the urijs library which is trying to construct an RFC6570 URL template.
However, I've tried and I can't reproduce your error message without your input definition and the command-line or options you're using. Please could you supply a gist showing what you're working with?
@MikeRalphson Here's a Gist, the any+ seems to be the problem. The OpenAPI Spec is auto generated from AWS API Gateway.
@MikeRalphson fwiw, https://editor.swagger.io also shows an error for the above Gist, but the routes do show up in the UI. I'm not entirely sure, if this is of any use for you to debug, but just wanted to mention it here.
Do you know what the + in the {any+} URL template is supposed to mean? According to RFC6570 the + "operator" can only appear at the start of a template, not at the end.
It is a combination of the fact that this {any+} template exists in the path, but a corresponding any+ in:path parameter does not exist which is causing the code to fail.
@MikeRalphson In this case, the {any+} captures undeclared path variables that are passed to the subresource chain, and are used to handle 404s. I believe there's also {proxy+}, wherein:
{proxy+} is a greedy path in which the entire sub-resource chain is passed to your backend as path variables.
(https://example.com/{proxy+} captures all of these sub-resources as path variables)
@MikeRalphson somewhat related to this: What would be the ideal way of defining how widdershins handles custom extensions, without ignoring them? A simple use case I have is defining an end-of-availability extension say like "x-deprecated-by", for a GET /endpoint and show it in the markdown generated by widdershins. AFAIK OpenAPI doesnt support this now as per https://github.com/OAI/OpenAPI-Specification/issues/782
Extensions should be accessible in the templates (i.e. if you modify or override them) as the objects passed to them in the data object are usually just decorated versions of what's in the input document. E.g. data.operation (see the template README), and the way the x-code-samples extension is referenced in operation.dot
{{? data.options.codeSamples || data.operation["x-code-samples"] }}