Apigee integration

[igorromcy]

Where is apigee integration? As I can see on this repo I need to run a local service to validate swagger doc.

[whitlockjc]

What Apigee integration are you looking for? This library has nothing in it specific to or directly supporting Apigee.

[igorromcy]

I'm trying to run this library inside an Apigee Edgemicro Plugin (EMG). So, there isn't any integration between EMG and this library, right?
I saw an integration with Apigee Edge, but I didn't see with Apigee Edgemicro. (https://github.com/apigee-127/a127-documentation/wiki/Quick-Start:-Deploy-To-Apigee-Edge)

[whitlockjc]

Let me see if @theganyo can help out, he's worked on Edge Microgateway more recently than myself. In theory, swagger-tools' middleware is just Connect middleware and doesn't do anything special for any environment/runtime but I'm not sure if EMG works with Connect middleware. Scott would know.

[igorromcy]

Okay, I'll wait news, thanks for the quick reply.

[theganyo]

No. There is no integration with swagger-tools and microgateway.

[igorromcy]

I hope I'm not annoying, just one more question, it's possible validate swagger doc without run a local server?

I tried initialize the middleware with metadata and swaggerValidator, so when I need to validate just calling: middleware.swaggerValidator() but seems like doesn't work

[whitlockjc]

What's the purpose? If you just want to validate the spec, the API. Otherwise, calling initializeMetadata will validate the spec and process.exit upon failure. While the reasoning behind process.exit is sound, the plan is to stop doing this as part of fixing #327.

[igorromcy]

The validation that I mentioned is about incoming request, for example:
I will send a GET to path: /pets
So, there is a json that I determine what method I want allow to each path, right?
Then I want to validate incoming stuffs with my pre-configured json without run a server, just calling middleware.swaggerValidator() I guess.

[whitlockjc]

middleware.swaggerValidator is the validation middleware. So if you want to validate requests/responses, use it instead of driving it yourself.

[igorromcy]

Yes, this is the guy that I want, but trying to validate without running a server seems like I need to do a lot of "workaround" that's not good.

[asnowfix]

Looking at https://github.com/apigee-127/swagger-tools/blob/master/docs/Middleware.md, it seems that middleware (and hence its .swaggerValidator() method) is only available & valid within the callback of initializeSwagger() which is itself callable only the initialization context.

What if we want to call the middleware ourselves outside of any init context?

middleware = XXX // how to get that value?

module.exports.init = function (config, logger, stats) {
  [...]
  return {
    onrequest: function (req, res, next) {
      middleware.swaggerValidator(req, res, function(err, data) {
        if(err) {
          return next(err)
        }
        /*do some other work, like per-parameter input-validation*/
        next()
      })
  }
}

[whitlockjc]

Well, this is more than possible but only suggested if you're 100% sure your Swagger document is valid. The whole purpose of initializeMiddleware is to validate your Swagger document and fail startup if it's not valid. _(I realize that failing the server because of this isn't ideal but the reasons behind it here and in #327.

As for doing this, you can require the middleware just like you would any other:

var swaggerMetadata = require('swagger-tools/middleware/swagger-metadata');
var swaggerValidator = require('swagger-tools/middleware/swagger-validator');

// ...
app.use(swaggerMetadata(yourFullyResolvedSwaggerDocument));
app.use(swaggerValidator());
// ...

Documentation on the middleware functions:

• middleware/swagger-metadata.js
• middleware/swagger-validator.js

[asnowfix]

Sounds good @whitlockjc : Seems like I can hook the Swagger documentation validation middleware to my own init context & then the individual req/res validation to the per-request context.

[ghost]

You might find the swagger-parser package helpful to ensure your spec is valid. Here's what we do in our app startup:

const swaggerParser = require('swagger-parser');

// Parse and validate a swagger document. Returns a promise.
// ex: parseSwaggerSpec( { swagger: 2.0, ... } ).then((parsed) => ... )
// ex: parseSwaggerSpec( './swagger/swagger.yaml' ).then ((parsed) => ... )

function parseSwaggerSpec(swaggerObjectOrPath) {
  return swaggerParser.bundle(swaggerObjectOrPath)
}

https://github.com/swagger-api/swagger-parser

[whitlockjc]

swagger-tools already does this, no need to point them elsewhere.

[ghost]

True, swagger-tools middleware does the parsing and validation. But when validation fails, the middleware calls process.exit(), which is a bit extreme for my use case. I'd like to catch and print out the validation error.

This is important for me because 20% of my swagger spec is built dynamically during my app's startup. I don't have a canonical .yaml file to run through a standalone validator. Calling process.exit() interferes with my unit tests.

Thanks for the reply. Apologies for derailing this thread.

[whitlockjc]

You're not derailing, I would just hate to see you moving to other things when there is no need. As for the process.exit() when failing to validate the input Swagger document, the validation failures are printed to the user. Your case is slightly different because you want to spin up a server with N individual Swagger documents and process them all. That will be addressed in #327. Worse case, if you'd rather validate your documents and drive things yourself, give sway a shot. It's written by me (the author of swagger-tools and similar).

[whitlockjc]

Also, if unit tests are the only reason you need to catch things, you can do the same thing that swagger-tools does in its tests and set RUNNING_SWAGGER_TOOLS_TESTS to true. It's not a real solution, something I'm fully aware of and will fix in #327, just a slight workaround if it helps.

[ghost]

Yeah, I recently learned about sway and am intrigued. It looks like a superset of the code I wrote to generate my swagger docs on the fly. The API looks useful, thanks.

Appreciate the tip re: RUNNING_SWAGGER_TOOLS_TESTS

[whitlockjc]

sway is pretty slick. The whole purpose was to build a real API around Swagger documents. swagger-tools' "API" is pretty crappy and was really intended for consumption by the CLI and middleware.