Migrating from Mojolicious::Plugin::Swagger2 to OpenAPI

Mojolicious::Plugin::OpenAPI is close to being stable so i figured it was time to migrate from our use of Mojolicious::Plugin::Swagger2. Here's the differences i found, with the observation that perhaps some of these were down to having an older version of Swagger2 (0.79, although Changes log suggests that might not be the case):

  • M::P::OpenAPI will, by default, validate response data. So you might find your swagger config and responses aren't in sync and/or you might bump into issues with how you have defined your response data (specifically null support).
  • M::P::OpenAPI doesn't support x-mojo-around-action, the idea of the new interface is to use the mojo router more directly.
  • M::P::OpenAPI expects the response information for all the various HTTP response code types that your app returns, most likely due to aforementioned response validation.
  • Each operationId within your swagger config must now be unique (as per the OpenAPI spec)
  • x-mojo-controller becomes x-mojo-to, and you can drop the top level of the namespace (the MyApp bit).

I have also updated the Swagger2-Markdown module to "support" multiple types in response object, although there are some issues there (see the commit message). I will probably get around to fixing that soon, although given how fast this stuff is currently moving other issues may arise sooner than that.

You may find the OpenAPI Spec useful if you're migrating, along with the Mojolicious::Plugin::OpenAPI::Guides::Tutorial. Note that my observations above may not be comprehensive either.

Leave a comment

About Lee J

user-pic I blog about Perl.