Clarify documentation

[theganyo]

1. Clarify that "context.output" should not be set directly as it is overwritten by the callback.
2. Document how "output" target values work.
3. Parallel pipes (especially the shortcut approach) should be introduced as a more advanced concept well after standard serial pipes have been completely explained.

[patrick-motard]

Hey theganyo,
I'm using swagger-node for an API and have a couple questions. My goal is to create middleware that is defined once, and registered to endpoints in the swagger.yaml of a swagger-node project. I apologize in advance if this isn't the best place to be asking these questions. If this is not the case please point me in the right direction.

• swagger-node was donated to swagger.io. Why is swagger-node being updated on both repositories? Why were apigee's other repositories like swagger-tools not also brought over to swagger.io? I'm forced to choose apigee's version if i want to use apigees other tooling around the swagger-node project because the tools aren't built around swagger.io's version. Maybe i'm misinterpreting somewhere?
• Does swagger-tools use bagpipes for it's security middleware? If not, would it be a good use case?
• Can i use middleware created/defined/registered/fitted/whatever using bagpipes in my swagger api yaml much like the security middleware?
• The examples in the bagpipes readme are single usecase only and not put in context of swagger-node's yaml. Where/how would bagpipes be used in swagger-node?

[theganyo]

Hey Patrick,

Sorry the docs haven't been updated yet, but I think the best place for you to start is here:

https://github.com/theganyo/swagger-node-runner/releases/tag/v0.6.0.
This is where swagger-tools was replaced by sway and everything was upgraded to first-class bagpipes fittings.

Once you've grokked that, you can take a look at this:
https://github.com/theganyo/swagger-node-runner/releases/tag/v0.6.10.
This explains the default way security handlers are now integrated. (But of course, you could use your own fittings, if you wished.)

I think that will probably give you all the background you need on how bagpipes is used within swagger-node-runner, but please let me know if you have more questions.

Scott

[patrick-motard]

Thanks for this information. Saved me quite a lot of time. I'm going to look over those documents and get back to you if unclear.