Merge Swagger Documents

[s-bauer]

Hey, I'm building a small microservice application to discover some best practices and get used to all the new tools and technologies. I'm using Ocelot to expose one unified API to the public which hides the implementation specific microservice architecture. Ocelot works very nice for this as I can do something like this:

Public API (v1)

• /users => Redirect to user-service with path /v1/users
• /posts => Redirect to post-service with path /v3/posts
• /media => Redirect to media-service with path /v3/media

Public API (v2)

• /users => Redirect to user-service with path /v2/users
• /posts => Redirect to post-service with path /v4/posts
• /media => Redirect to media-service with path /v3/media

As you can see, one public api version bundles different versions of the specific microservice into one uniform API. With a version update to the public-api I can change any version of the downstream microservices as shown above.

I've found this Swagger Generator for Ocelot and I must say it's completely amazing! I'm just missing one important feature for my scenario which I don't think is yet implemented. I want to merge the three swagger documents of the downstream microservices into one unified Swagger Document which I could distribute to the public. It should hide that there are several microservice working together in order to provide the backend for this API.

I'm guessing it's already possible to implement this with all the customization options offered by this library. Maybe you can point me into the right direction on what's the best way of implementing this into the existing project. In case time allows it, I would be glad to contribute this feature to the library!

[Burgyn]

Hi @s-bauer,

thank you for sharing your idea. Sounds like a logical requirement.

If I understand correctly, instead of the documentation being divided into micro services, do you want it to be in one document?

---

Middlware SwaggerForOcelotMiddleware, handle requests from SwaggerUI.
In the current implementation, finds the corresponding endpoint by path and downloads the documentation of the corresponding service. It then uses ISwaggerJsonTransformer to modify the documentation to match how the client will call it via Ocelot.

I would suggest the following procedure. Have a setting that determines whether the documentation should be merged into one document or behave as before.
Extract the current body of the Invoke method in the middleware to a separate class shaded by the interface. Then create a new implementation of the interface that will execute your scenario. It will probably download the documentation for all services.
It transforms each document by ISwaggerJsonTransformer and somehow merges into one document. In the configuration decides which implementation to inject.

However, I have the following questions (possible problems)

1. Performance.
   A real, larger project has tens/hundreds of micro-services and each has rich documentation. Downloading and processing this data will be quite a long operation.
   It would be worth considering allowing the generated documentation to be saved for further use. (Abstract of the storage provider, because not everyone can write directly to the disk)
   Also devise a way to invalidate this data.

2. Different Scheme in different services
   With a larger number of services, it is likely that two services will refer to types with equal names but different properties. What in this case? Ideally, it would be a post-process to modify the names of those types by adding the name of the service. But I find it quite complicated.

3. Gateway ItSelf and Aggregates
   This package show documentation for gateway itself and generate documentations for Aggregates as separate documents. Currently I'm not sure how to merge it.

---

This is not a simple implementation. Currently, I don't need to work it out. However, I understand that this may be important to you. I will be very happy if you start implementing it. Feel free to address me with questions. (Currently I will have 3 weeks holiday, so I will answer only after that)

When implementing, please do not forget about unit tests and few words to documentation in readme.md.

Thank you very much again.