Customizing Swagger-js for vendor extensions

[scout387]

Hello,

I will start with the example of I want to simulate.
Go to: http://docs.sencha.com/extjs/4.2.5/#!/api

Below the Tree View for the API documentation, there is a "Show private classes" checkbox. By default they only show the API of the classes you will use, but for your convenience, they offer the option to see the internal classes (which are not recommended to use), you just have to check "Show private classes".

So, in my company we are using older versions of Swagger, and we want to upgrade to newest versions. We have a similar situation with EXTjs. We have a REST API, and we documented all our routes for the convenience of our clients, and developers. But now we would like to differentiate between internal routes used by our developers, and the external routes used by our clients.

I have read most of Swagger's documentation, and I realized that I will have to implement it by myself.

My first approach was:

1. Added a vendor extension to the Swagger "x-internal" which can hold a boolean.
2. I would customize Swagger-UI to get that API, read the "x-internal" field, and finally just display what the user wants to see.

My problem is:
I noticed that Swagger-UI depends on SwaggerClient, which is doing the hard work. SwaggerClient is not consuming the "x-internal" field, and it strip it away.

So! I am here to see if someone has done something similar to this, and/or if they have a better approach. I am guessing that I will have to customize first Swagger-js, and then customize Swagger-UI.
I think I understand quite well (or at least partially well) Swagger-UI, but now I will have to understand the source code of Swagger-js, so it will be of great help if you guys could give me hits of where I need to do the changes.

[fehguy]

Hi, your approach is correct, adding support inside the swagger-js client then exposing them in swagger-ui.

[fehguy]

#869 adds all extensions to the client prototype.