Swagger2: "The World's Most Popular Framework for APIs"

[Jan Henning Thorsen]

Hi,

I'm working on a new module that takes advantage of the Swagger2 API documentation format.

https://metacpan.org/release/Swagger2

https://metacpan.org/release/JHTHORSEN/Swagger2-0.03 (in case 0.03 isn't visible from the line above)

Features:

* Automatic route generation

* Input/output validation in your Mojoliicous applicaiton

* Swagger documentation to Perl documentation (POD)

* JSON Schema validation

Plans:

* Add Swagger::Client which wraps around Mojo::UserAgent and enables input/output validation

Any feedback/ideas are very much appreciated.

[Justin Hawkins]

Hi Jan,

Interesting idea!

I hacked for a while on essentially the reverse - generate the swagger JSON data from the Mojolicious routes + POD documentation. Thus the actual code and inline documentation becomes the source of truth for your API specification.

Maybe I need to pick it up again :-)

https://github.com/tardisx/mojolicious-command-swagger

- Justin

[Jan Henning Thorsen]

Looks interesting Justin!

How would you feel if i changed your code into a Swagger2 command and merged it into my project? You could also be co-auth, if you like...

I've been thinking about a swagger (or swagger2 command), which could convert the API description into POD. Something like this:

  $ mojo swagger pod path/to/spec.json

I guess if I could merge your module, there would also be a --version switch:

  $ mojo swagger json --version 1.2 lib/YourApp.pm

Not sure if that makes any sense though, since my module is called Swagger2.

[Helmut Wollmersdorfer]

Am Dienstag, 9. Dezember 2014 16:02:11 UTC+1 schrieb Jan Henning Thorsen:

Any feedback/ideas are very much appreciated.

May I suggest that you unbundle it into two distributions

- Swagger2 (without dependency on Mojolicious)

- Mojolicious::Plugin::Swagger2

The reasons:

- the different top-level namespace

- minimal dependencies

- Swagger2 could be useful for other frameworks too

Looking into the code I now saw that Swagger2 uses Mojo::Base & Co, which I understand as convenient (I also did this for some CPAN modules, but removed it before first release), but which IMHO isn't necessary.

[Jan Henning Thorsen]

Hi,

I can understand the argument about different top-level namespaces, but...

Swagger2 depends on Mojo::JSON, Mojo::JSON::Pointer, Mojo::URL and Mojo::Util. I don't want to depend on other modules, just to avoid Mojo:: modules. Even so...I don't _think_ I would mind pull-requests to make it work with Mojo:: modules and/or other CPAN modules.

Swagger2 can be used with other frameworks as well. Just use the Swagger2 module and skip the plugin. Mojolicious need to be installed though, because of the reasons i mentioned above.

[Justin Hawkins]

On 10 Dec 2014, at 5:26 pm, Jan Henning Thorsen <jan.h...@thorsen.pm> wrote:

Looks interesting Justin!

How would you feel if i changed your code into a Swagger2 command and merged it into my project? You could also be co-auth, if you like…

If you can find something of use in my code, please do so :-)

I've been thinking about a swagger (or swagger2 command), which could convert the API description into POD. Something like this:

  $ mojo swagger pod path/to/spec.json

I guess if I could merge your module, there would also be a --version switch:

  $ mojo swagger json --version 1.2 lib/YourApp.pm

I wasn’t wedded to supporting 1.2 at the time - it was only that 2.0 wasn’t mature. I’d probably target that now.

- Justin

[Jan Henning Thorsen]

Cool!

Pull requests are also welcome :)

[Rajasekar Venkatesan]

Hi,

[Jan Henning Thorsen]

Version 0.12 contains a mojo command which can validate and generate pod. It also contains a webserver which allow you to view/edit the spec in your browser:

  $ mojo swagger2 edit petstore.json --listen http://*:5000

Unfortunately, I had to disable the "not" schema validation in 0.12 while fixing another bug with $ref's that was not expanded. Patches are welcome to get it back in. (I will look at it as soon as I have the opportunity)

[Jan Henning Thorsen]

I've put a demo of the editor online now if anyone wants to see.

https://ssl.thorsen.pm/swagger2