Hello,

I am the maintainer of the OpenAPI module. OpenAPI also provides a swagger UI module, with support for its libraries. On today's API-First Initiative weekly, @wim-leers mentioned to me that development on this module had been started again.

I would like to propose collaboration between the openapi module and this module, as they both serve similar communities and requirements. Additionally, there is no reason for two projects to be requiring the Swagger UI library, and displaying it in separate implementations.

The proposal would be to provide an openapi_ui module, which would provide support for displaying the openapi/swagger defined specs as ui elements. That project would then contain the implementation of Redoc (Currently bundled with the OpenAPI module) and Swagger UI display. It may also be worth resurrecting Docson.

I would be willing to handle the implementation of the collaboration module, as it would make the OpenAPI module lighter. The general design would be to implement the OpenAPI docs, via plugin to the new module. A similar plugin could also be provided by this module, to control the display. I believe this change is where I will be heading with OpenAPI in the near future, please let me know if this implementation is seen as a benefit. I believe it would also be logical to implement the ui libraries as Render Components which my benefit this module significantly.

Let me know if you have any thoughts, questions, or concerns

Thanks,

Rich

Comments

richgerdes created an issue. See original summary.

richgerdes’s picture

richgerdes
he/him
Primary language English
Location New Jersey, USA
CreditAttribution: richgerdes commented
Issue summary: View changes

Typo

Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers at Acquia commented
Issue tags: +API-First Initiative
Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers at Acquia commented

Pinged the CEO of Pronovix, the company behind this module: https://twitter.com/wimleers/status/1018861437278662658

balazswmann’s picture

balazswmann CreditAttribution: balazswmann commented

@richgerdes thank you for the initiative!

I took a deeper look to the OpenAPI module (including its submodules) and as I see it serves a completely different purpose then this field formatter module. The only common thing in the modules is that they are using the same Swagger UI library but I don't see this as a problem. I'm sure that there are lots of modules out there which are using the same library but provide different functionalities. In other words: this in itself shouldn't be a reason to merge those modules.

If someone needs only the a field formatter because s/he just wants to visualize OpenAPI documentations of an external service it wouldn't really make sense to install the complete "OpenAPI suite", which is basically built to visualize the REST API that you expose in Drupal. If we would go into this direction then sooneer or later every OpenAPI and Swagger related custom module would end up in the OpenAPI module just because of the common library. I don't think this would be beneficial. The usage of the Swagger UI library is so simple that it wouldn't make sense to create a base module for some kind of generalization upon it.

So my conclusion is that it's ok to have these modules separately.

richgerdes’s picture

richgerdes
he/him
Primary language English
Location New Jersey, USA
CreditAttribution: richgerdes commented

@balazswmann, I agree completely. I am not proposing merging the modules. I fully agree that the openapi and formater modules don't server the same users. I however am suggesting that we depend on the same version of the swagger ui library in order to allow a cleaner experience.

The proposal was to develop a third project, which both openapi and this module could use which would supply the swagger ui in a reusable way, which could be leverages not only be this module and openapi, but also potentially other modules down the road.

For a while I have been considering factoring out the UI components from the OpenAPI project into its own library while refactoring them to use plugins. I have recently published a new module, OpenAPI UI, which implements this abstracted version of the ui. I am working on a patch, to make openapi provide expose its docs using this new library, if it is present. This new library provides a render element, which handles rendering the Swagger UI as to not require it in openapi. The actual swagger UI is provided by a new Swagger UI module. Using this new OpenAPI module, it also allows for the user to optionally use other uis, such as ReDoc, for viewing the documentation.

The proposal above would be for this module to leverage the OpenAPI UI module in the Formatter, which would allow the project to not directly require the swagger ui, and to provide support for alternative uis, without this module needing to implement the integration.

At this point, I am just offering it to reduce the burden of this module's maintainers, but using the new project is in no way a requirement. I am happy to work with you and the team behind this module to make any changes to the SwaggerUI and OpenAPI UI modules that would benefit this project. Chiefly, I am sure #2987432: Support Multiple UI Instances on the same page would be desired, as well as extensions to handle passing authentication and other metadata to the rendered doc, which I plan to do down the road for better compatibility with the OpenAPI module.

Let me know if you have any further questions. If you have an interest in using the new ecosystem, I am happy to put together a preliminary patch which moves this along.

mxr576’s picture

mxr576
Primary language Hungarian
Location Hungary
CreditAttribution: mxr576 at Pronovix commented

It sounds more like to me a born of a new module, called openapi_field_formatter, because in this project we do not need a "plugable" formatter, we only want to use Swagger UI. Of course, when this new module will be born this module gets deprecated.

richgerdes’s picture

richgerdes
he/him
Primary language English
Location New Jersey, USA
CreditAttribution: richgerdes commented

I think that this module, could still leverage the other library, but I would agree that its not worth the significant changes to this module in order to implement alternative uis.

I at this time don't use this module and don't have a need to develop the more advanced version. As a result, its not ideal for me to build out the new project, but would be happy to collaborate with someone on the development of it. Let me know if your team wants to go further with it (or if someone else wants to spearhead the development)

richgerdes’s picture

richgerdes
he/him
Primary language English
Location New Jersey, USA
CreditAttribution: richgerdes commented

@mxr576,

I wanted to start moving this project along as I have a use case for it. Would you be able to transfer me ownership of the new project (openapi_field_formatter) so that I can start work on it?

Thanks in advance.

mxr576’s picture

mxr576
Primary language Hungarian
Location Hungary
CreditAttribution: mxr576 at Pronovix commented

Hi, richgerdes!

I added you to the project. We'll try to assign someone from our end to this project so you could consult with him/her about what you would like to implement exactly and how you would like to implement it so you can work together on this.

@balazswmann from us already has access to the repo, he created the 8.x port of the Swagger UI field formatter, but he has limited available at this moment.

kvantomme’s picture

kvantomme CreditAttribution: kvantomme at Pronovix commented

Quite some time has passed since this issue was created, @richgerdes are you still interested in collaborating with us on this?

andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented
Status: Needs review » Active

No patches to review