Serve openapi.yaml file as documentation page

[magicmatatjahu]

We should serve our openapi.yaml document as separate page using https://github.com/swagger-api/swagger-ui or https://github.com/Redocly/redoc

AC:

• serve on /openapi (or another like /docs, we should discuss name of that path) the openapi.yaml spec

Before contribution please start discussion to clarify implementation and your questions/problems :)

This problem is involved in the OpenForce event. Please don't contribute if you are not participating in this event. If the problem is not solved at the end of the event, feel free to contribute :)

[BOLT04]

we are using OpenAPI 3.1.0, and it seems Redocly has basic support for it. I'm most familiar with swagger-ui but it doesn't seem to fully support 3.1.0 yet: swagger-api/swagger-ui#5891.

@magicmatatjahu and @smoya what do you think is the best choice here?

[magicmatatjahu]

@BOLT04 I also more familiar with swagger-ui and it has an excellent support for testing that spec (by test it functionality) but I think that we should go with redocly. As I remember it also support "test it" and have a nicer UX and styling. Of course if you wanna handle that I can help you :)

I found also that nice middleware that we can reuse :) https://github.com/AungMyoKyaw/redoc-express#readme

[BOLT04]

then let's go with redocly 👍, we can always contribute to the project if we need support on something the library doesn't yet support 😃

[magicmatatjahu]

@BOLT04 Could we make it as part of the OpenForce event or do you wanna contribute it? More info asyncapi/website#599

[BOLT04]

yessss let's make it a part of the OpenForce event 👍. New contributors are always welcome 😃

[everly-gif]

Hi , I would like to work on this issue as part of the openforce event. Could you assign it to me?

[everly-gif]

As per previous comments, I plan to implement it using redocly and will be creating a display using the openapi.yaml file which will serve as documentation. Regarding the path would you like for me to create a folder named docs and create a index.html file(which will contain the intergration with redocly) inside it?

Here's something I have generated with redocly:

Is this what you are looking for?

@magicmatatjahu

[magicmatatjahu]

@everly-gif You can handle that.

As per previous comments, I plan to implement it using redocly and will be creating a display using the openapi.yaml file which will serve as documentation. Regarding the path would you like for me to create a folder named docs and create a index.html file(which will contain the intergration with redocly) inside it?

But that page should be visible on the server side, so you need to handle that by some static-serve lib or something like that. Please check some open source libs which integrate redoc in express like this one https://github.com/AungMyoKyaw/redoc-express#readme :)

[everly-gif]

Hi @magicmatatjahu I'm looking into https://github.com/AungMyoKyaw/redoc-express#readme could you tell me where would it be appropriate for me to add the code. I believe I should be editing app.ts right? I'm quite new to typescript but am familiar with node and express.

[magicmatatjahu]

@everly-gif You should create controller in the https://github.com/asyncapi/server-api/tree/master/src/controllers folder as docs.controller.ts. You can make it similar to the validation.controller.ts and then connect it to the app in https://github.com/asyncapi/server-api/blob/master/src/server.ts#L13 :)

[magicmatatjahu]

Implemented by 0d4a418