How to integrate Swagger UI?
Hi @kapa.ai, can you explain me how can I integrate Swagger UI into a Wasp project? Thanks!
11 Replies
Hi @mario.p. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
I don't see specific information about integrating Swagger UI with Wasp in the provided knowledge sources. Wasp provides a way to create custom HTTP API endpoints using the
api declaration, but there's no direct mention of Swagger UI integration in the documentation provided.
Since Wasp uses Express under the hood for its API endpoints, you might be able to integrate Swagger UI using standard Express middleware, but I can't provide specific instructions based on the available knowledge sources.
If you're looking to document your API endpoints, Wasp does allow you to create custom HTTP API endpoints with specific routes and methods as mentioned in the Custom HTTP API Endpoints documentation, but for Swagger UI integration specifically, you might want to check the official Wasp documentation or ask in the Wasp community Discord for more targeted guidance.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------
Sorry @mario.p, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist:
Perhaps try again in 15mins?Hey @mario.p, I've never used Swagger in JavaScript so I'm not sure whether you'll have an easy or a hard time integrating it.
Have you tried anything? How is it working out?
@mario.p this was something I had way down on my backlog, but your question prompted me to try and play with it for a bit, but from what I've found so far, it doesn't seem possible right now.
I attempted a few different approaches:
1. Implementing Swagger directly. This involved installing the possible practical.
swagger-jsdoc and swagger-ui-express packages, creating a new api namespace with middleware for the Swagger UI at the desired path. I also found I needed to install helmet so that I could disable CSP and HSTS at that path, for the docs to be rendered.
However, the conclusion was that because Wasp generates the final routes, there's no way to define the JSDoc comments in a persistent way in your source code, so the output was always empty (I did verify that adding comments to the built code works, but obviously that’s not maintainable).
2. I then tried to use express-oas-generator, but they want you to hook into specific points of the express server lifecycle, which Wasp doesn't expose, so I left that one alone.
3. Finally, I attempted using swagger-autogen and while it can generate the basic route definitions, I was faced with the same problem as #1 above, where there's no way to define the necessary comments in the generated code.
Happy to be corrected by a member of the team, but as far as I can tell, it's not currently Thank you @genyus for trying to do it! If Wasp included the JSDoc comments, would it work out of the box somehow?
@genyus Do you mind posting this as a comment on https://github.com/wasp-lang/wasp/issues/863
I can copy-paste it myself, but you deserve the credit 🙂
GitHub
Automatically expose documented API based on the defined Operations...
We could use Swagger or Openapi for this, or something similar! It would also make sense to first work more on allowing users to define which API is public, should not change, allow them to customi...
Yes, if the comments could be carried through, it would be work once Swagger is installed and configured
Thanks, will do
Thank you everyone guys for help!
Thanks to a suggestion from @martinsos, I've been able to get this working and created a Gist to detail the necessary changes. I use Typescript configuration files, so that's what's in my example, but you can add the JSDoc comments in main.wasp if that's what you use.
Gist
Enable Swagger documentation for Wasp APIs
Enable Swagger documentation for Wasp APIs. GitHub Gist: instantly share code, notes, and snippets.
@genyus this is amazing, do you have some screenshots of the Swagger UI? 😄 I'll add your gist to our learning materials: https://github.com/wasp-lang/learning-materials/blob/main/README.md
GitHub
learning-materials/README.md at main · wasp-lang/learning-materials
A place to collect some useful learning materials for Wasp - wasp-lang/learning-materials
@miho if that helps, we tracked this so far in this issue, and @genyus also linked to his gist in it at the end: https://github.com/wasp-lang/wasp/issues/863#issuecomment-2779505375
GitHub
Automatically expose documented API based on the defined Operations...
We could use Swagger or Openapi for this, or something similar! It would also make sense to first work more on allowing users to define which API is public, should not change, allow them to customi...
Added a screenshot to the Gist