search

mac- / ratify

A Hapi plugin for validating the schema of path, query, request body, and response body params using JSON-schema
MIT License
71 stars 27 forks source link

Basic hooks to customize swagger generation #18

Closed dschenkelman closed 10 years ago

dschenkelman commented 10 years ago

Useful hooks to customize how some swagger elements are generated. They are optional and do not prevent default behavior if provided.

coveralls commented 10 years ago

Coverage Status

Coverage decreased (-0.4%) when pulling c50820ac6cf470f1007ae242857d6315210db9fc on dschenkelman:customizeOperationDoc into 1a5edb54e9b6f1908631dc4931929259447c0bc5 on mac-:master.

dschenkelman commented 10 years ago

@mac- any thoughts on this one?

mac- commented 10 years ago

Can you give me an example of what one of these swagger hooks look like? Why would we want to modify the swagger output? Is there a use case that ratify isn't configured to handle that it maybe should?

dschenkelman commented 10 years ago

We have an authorization format, based on JWTs and need to be able to tell ratify how to generate the swagger for it. When using swagger-ui we customize the rendering to display the scopes that give you access to a particular endpoint, but we need to have those available in swagger first:

swaggerHooks: {
  operation: function(operation, route, resourceType, path){
    if (route.settings && route.settings.auth && route.settings.auth.scope){
      var scopes = route.settings.auth.scope;

      operation.authorizations = {
        jwt: {
          scopes: scopes
        }
      };
    }
  }
}

It still has to be valid swagger (otherwise when processing with swagger-ui you get errors), but allows you to customize some things that might be app specific.

mac- commented 10 years ago

ahh ok, so you are running a customized version of the swagger ui?

dschenkelman commented 10 years ago

Yes, which I think is fairly common since their templates can be modified. Still, even if we weren't having those hooks available provide an additional extension point that allows users to adjust ratify to their scenarios without the need to perform changes to the lib. If enough people then want a particular mapping based on standards or something it can be implemented in ratify itself...

mac- commented 10 years ago

I'll publish a new version tonight

dschenkelman commented 10 years ago

Great! No rush on my part, I'm pulling the package from my fork right now