Migration from Swagger 1.2 to 2.0

Do I have to do this?

Compojure-api version before 0.20.0 use the Swagger 1.2 format while 0.20.0 and above use Swagger 2.0. So, if you have a web-api using pre 0.2.0, this is for you.

Everything explodes?

Should not, the deprecated macros are still there, complaining to STDOUT of their existence.

Steps

Update the dependencies

Both the Compojure-api & The (Ring-)Swagger UI

Compile your routes

by evaluating the defapis. There are two meta-data handlers that have changed. If you have used them, the route compilation fails. If it does, convert the new metadata-keys with the mapping below:

• :nickname --> :operationId
• :notes --> :description

dry-run you app

Most probably your app now starts and works as before, but you are getting loads of warnings to STDOUT. Let's remove those.

Swagger 2.0 Information model

The swagger-docs input format has changed in align to the new spec. If you have defined any parameters to it, they should be changed.

note you can now pass any valid Swagger data in via swagger-docs. Cool.

Old

(swagger-docs "/api/api-docs"
  :title "Cool api"
  :apiVersion "1.0.0"
  :description "Compojure Sample Web Api"
  :termsOfServiceUrl "http://www.metosin.fi"
  :contact "[email protected]"
  :license "Eclipse 1.0"
  :licenseUrl "http://www.eclipse.org/legal/epl-v10.html")

New

(swagger-docs
  {:info {:title "Cool api"
          :version "1.0.0"
          :description "Compojure Sample Web Api"
          :termsOfService "http://www.metosin.fi"
          :contact {:name "Pizzaman"
                    :email "[email protected]"
                    :url "http://www.metosin.fi"}
          :license {:name "Eclipse 1.0"
                    :url "http://www.eclipse.org/legal/epl-v10.html"}})

You should now get rid of the DEPRECATED: swagger-docs - :license is deprecated, see docs for details. -warnings.

Remove the swaggered-macro

Routes are collected now from the root, namely by the compojure.api.routes/api-root macro. If you use defapi, it does it for you. With 2.0, apis are categorized by tags, which can either be anonymous or defined. Defined tags are presented with the swagger-docs. Tags are set via meta-data either to endpoints or to mid-route via context*.

Old

(defapi app
  (swagger-ui)
  (swagger-docs)
  (swaggered "api"
    :description "the beer api"
    (context "/api" []
      (GET* "/ipa" []
        (ok {:sider false})))))

New

(defapi app
  (swagger-ui)
  (swagger-docs
    {:tags [{:name "api", :description "the beer api"}]})
  (context* "/api" []
    :tags ["api"]
    (GET* "/beer" []
      (ok {:sider false}))))

You should now get rid of the DEPRECATED: swaggered is deprecated and removed soon, see docs for details. warnings.

Clean up the defroutes* mess

With the awesome backtick, the #42 is finally fixed.

You don't now have to import all models from different files to the namespace where the defapi resides, just the defroutes* Vars.

Finalizing

All is good when no DEPRECATED -warnings apper on the console. The new default swagger-spec location has changed from /api/api-docs to /swagger.json, so if someone depends on that and you haven't specified it manually with swagger-docs, distribute the new uri.

Enjoy!