Curly brackets in URLs

[KevinColemanInc]

I am having trouble generating source code from documentation generated by this tool.

I opened a ticket with the codegen devs, but they are thinking this is an issue with the tool

https://github.com/swagger-api/swagger-codegen/issues/379#issuecomment-70694922

Basically, they don't think you should be using curly brackets in the urls.

Any thoughts?

[dblock]

I don't believe grape-swagger generates things like these or it shouldn't matter. Care to build a case that reproduces this problem?

[KevinColemanInc]

I haven't used grape or grape-swagger, so I am kinda winging it here, but I see in one of your rspec tests, you are verifying that the outputted json has .{format} in it

https://github.com/tim-vandecasteele/grape-swagger/blob/e977feac26d2ba125d92067e3f6a433738415131/spec/simple_mounted_api_spec.rb#L77

[dblock]

Fair enough, but it hasn't been a problem for anybody, so why and how is it "not working"? With a repro we can take a look.

[KevinColemanInc]

@dblock I have one of the swagger devs saying this is not best practice.

"using curly braces in actual URLs is... not recommended" -@webron from swagger.io https://github.com/swagger-api/swagger-codegen/issues/379#issuecomment-70694922

Have you had other people successfully use the swagger-codegen to generate code from documentation generated by this gem?

[dblock]

Best practice and bug are two different things. I think we should narrow down why it's not working first before we go changing things.

Haven't worked with swagger-codegen personally.

[josephmisiti]

@KevinColemanInc trying to do that right now and hitting the exact same problem as you

ValidationError(articles:api/articles.json:get,responseClass is required,ERROR)
ValidationError(articles:api/articles/{id}.json:get,responseClass is required,ERROR)
ValidationError(articles:api/articles/{id}.json:put,responseClass is required,ERROR)

[webron]

From RFC 1738 -

   Unsafe:

   Characters can be unsafe for a number of reasons.  The space
   character is unsafe because significant spaces may disappear and
   insignificant spaces may be introduced when URLs are transcribed or
   typeset or subjected to the treatment of word-processing programs.
   The characters "<" and ">" are unsafe because they are used as the
   delimiters around URLs in free text; the quote mark (""") is used to
   delimit URLs in some systems.  The character "#" is unsafe and should
   always be encoded because it is used in World Wide Web and in other
   systems to delimit a URL from a fragment/anchor identifier that might
   follow it.  The character "%" is unsafe because it is used for
   encodings of other characters.  **Other characters are unsafe because
   gateways and other transport agents are known to sometimes modify
   such characters. These characters are "{", "}", "|", "\", "^", "~",
   "[", "]", and "`".**

[dblock]

Can someone help me see the problem, maybe a test project?

[webron]

I'm about to board a plane, but maybe we can set to talk sometime in our IRC channel? It may be easier to explain instead of going back and forth with comments. On Jan 30, 2015 6:38 AM, "Daniel Doubrovkine (dB.) @dblockdotorg" < [email protected]> wrote:

Can someone help me see the problem, maybe a test project?

— Reply to this email directly or view it on GitHub https://github.com/tim-vandecasteele/grape-swagger/issues/197#issuecomment-72188937 .

[dblock]

Someone who understands what/why/where should fix the problem in a way that works for everybody, really.

[webron]

The solution should be simple. As far as I understand, the paths listed in the resource listing (that is, the api-docs) all have a .{format} extension and the api declarations themselves are hosted using the .json extension.

The solution can be one of two:

1. Replace the .{format} extension with .json and that would be just fine.
2. For consistency, remove the .{format} altogether and remove the .json extension as well from the hosted api declarations.

[dblock]

APIs that are JSON by default omit and no longer respond to .json btw.

[webron]

Okay, but keep in mind I'm talking about the actual API operations but rather the the Swagger documentation endpoints produced by grape-swagger.

[dblock]

Yes. Either way I would take a PR that does this.

[webron]

Wish I could help there, unfortunately my knowledge of ruby ends with about recognizing the file extension.

[dm1try]

So just to clarify(or add more noise:)) We should not use {format} at all.

The main point:

1. grape-swagger root response(/swagger_doc by default) includes resources listing(RL) paths
2. grape-swagger RL object('/swagger_doc/resource' for example) includes apis definition(AD) paths

Removing {format} from RL and AD paths should be separated.

1. We already have format option in grape-swagger which applied for endpoints generated by grape-swagger (RL endpoints) but it does not affect RL paths. We can use it to generate RL paths with/without extensions. As for me I would just a specify :json format by default in grape-swagger and remove format option at all. Because it only used to generate proper RL path, so nevermind if extension applied or not.
2. We should generate AD paths with/without .json extension using grape application(API) format settings(not a grape-swagger).

am I right?

[dblock]

I think @dm1try is right.