search

Luracast / Restler

Simple and effective multi-format Web API Server to host your PHP API as Pragmatic REST and/or RESTful API
http://luracast.com/products/restler/
GNU Lesser General Public License v2.1
1.36k stars 316 forks source link

Swagger 2.0 #382

Closed yankeeinlondon closed 9 years ago

yankeeinlondon commented 9 years ago

Swagger 2.0 is now live. Any plans to bring that goodness over to Restler?

Side note: I think the current change notes could be clearer on where the 1.2 spec came into 3.x release. Also, there's still a 1.2 branch but that appears to be out of date now that 1.2 has made to the 3.x releases; I think it may make sense to remove that unless it's still serving a function.

yankeeinlondon commented 9 years ago

Also on this thread ... I think your plan was to bring the API functionality into the Restler repo rather than having the API Explorer repo as a side car. If that's true than you might want to consider making note of the fact that API Explorer is now deprecated at the top of the README.

yankeeinlondon commented 9 years ago

Also in a case of "version collisions" the last commit to API Explorer says something to the effect of "upgrade to v2" which I assume was a reference to the Restler version and not the Swagger version. At this stage it would probably be many's assumption that this was a reference to Swagger version. I point this out for two reasons:

  1. It in effect re-emphasizes the importance of having a importance of having a "deprecated" message on the README
  2. It also highlights that there is no clear referencing of the version of Swagger being used ... I think both for attribution and visibility reasons it would be good to be quite explicit about this.
Arul- commented 9 years ago

@ksnyde thanks for your suggestions, I will do them one by one!

Arul- commented 9 years ago

@ksnyde updated the readme of the api explorer project to let every one know about the newer version :)

yankeeinlondon commented 9 years ago

Great thanks.

roynasser commented 9 years ago

Sorry guys, but how is Explorer used now? I changed the add api class from Resources to Explorer... Should I expose the files in the explorer dir (html/css/js) to my webserver? /API/resources.json now yields 404.... /explorer.json also doesnt work?

Arul- commented 9 years ago

@RVN-BR just add Explorer as the api class and then point your browser to /explorer

resources.json is now under /explorer/resources.json

Good thing about this is, you can use the second param to change explorer to whatever you like

$r->addApiClass('Explorer', 'swagger');
// now /swagger gives you the explorer interface
roynasser commented 9 years ago

Aha! I see, will test it now... :) Our webserver separates static content from dynamic content, I hope this isnt too much of an issue... let me poke... :+1:

(on another note - didnt want to open another issue as i'm not sure what to consider - was there any change in RC5>RC6 where multiple routes defined by comments are no longer supported? we seem to be considering only the first route? more on this in a bit after I get explorer going :dash: )

Arul- commented 9 years ago

@RVN-BR multiple manual routes should be supported

roynasser commented 9 years ago

Thanks to API explorer its now clear there is something wrong with the accept type of POST requests.... (my bad, POST was after GET on the first few failed methods I found...lol)... I didnt find an accept config in default, its weird I'm getting Forbidden: Content type text/plain is not supported but only for POST requests... and no matter what response content type I select)...

As a note, HTML Response Content is breaking Explorer layout... perhaps it should be disabled?

Arul- commented 9 years ago

As a note, HTML Response Content is breaking Explorer layout... perhaps it should be disabled?

@RVN-BR Not sure! can you share more info and a screen shot?

Arul- commented 9 years ago

When you use POST, request body can't be blank which is the reason for xml or text content type. Make sure there is some json body all else will be fine

roynasser commented 9 years ago

Sure, I will attach normal JSON Explorer output, and "broken" HTML output... of the same method... image

HTML: (top): image

(below): image

roynasser commented 9 years ago

About the text/html error, what do you mean json body? This APIs receive input from regular web forms, they are supporting an existing web app, its not possible to change the input format... Are request variables no longer supported? Is there a log somewhere of the changes of RC5->RC6? We are a bit afraid of moving RC6 into testing, then production as we arent really sure what to expect in terms of changes?

roynasser commented 9 years ago

Upon further testing I'm having different behavior and different errors based on inverting the route comment, like so:

GET /method POST /method

and

POST /method GET /method

produce different requirements/errors, etc... but only on RC6.... I will revert to 5 for now as I have some ppl breathing down my neck now :( sorry I cant contribute more right now...

yankeeinlondon commented 9 years ago

@RVN-BR that sounds like an odd problem considering sequence of calls shouldn't be able to make a difference considering Restler is stateless. I suspect there must be something stateful happening with your scripts which is causing this variation. Of course I'm sitting in a proverbial dark room with zero context to your details but still the pure logic of of my argument seems to make sense to me. :)

Hope that helps; it would be great if you could come back to this thread when you've got a few cycles as it'll be very hard for anyone to reproduce this at the moment.

@Arul- I do think @RVN-BR suggestion of an actively managed CHANGELOG.md (or similar) might be very helpful for people considering the migration process. In my experience it can be a not insignificant task to do retroactively but maybe just getting it started now we will start to have this resource as a reference document. Certainly in the formal 3.0 build it seems like a very good idea.

roynasser commented 9 years ago

Yeah... I'm also a bit in the dark as this was reported by another developer, I was able to see it happening, but I cant say what it is... I thought it was an encoding issue or accept type issue, but for some reason, I'm getting different errors on different orders of the methods, and different formats requested/sent... What I do know is that RC5 is working fine and RC6 is not, so before I can fix it it would be good to knw what changed ;)

Yes, doing a changelog retroactively is a nightmare, but the earlier it gets started the better it is... There is an overall changelog, but more detailed things arent there, and RC6 changes still arent there at all... When trying it out its very hard to debug... We have hundreds of methods and serve a couple of apps with the API, any updates can break things we dont even imagine, even if tests are passing... a changelog would be really useful and would ease a lot migration as @ksnyde mentioned... I can second that all migration processes were a bit traumatic, and would have been eased with a changelog/migration path had one existed

all the best! I'll try and get more info when I can...