marshmallow-code / marshmallow-code/apispec
Documentation to explitly specify how to serve Swagger UI using apisec ?
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 202
- Avg merge
- 3h 38m
- Merged PRs (30d)
- 3
Description
Perhaps this is too obvious for most, but I struggled a bit figuring out how to use the result of my apispec to actually serve a Swagger UI from my Flask app.
I think other noobs might benefit if the documentation laid out clear steps on how to serve a Swagger UI, for example using Flask. I finally figured this out from this blog post [here](https://dev.to/sanjan/how-to-add-swagger-ui-to-a-plain-flask-api-project-with-an-openapi-specification-file-1jl8) after a few hours of researching different solutions.
Beginners might waste a lot of time researching third party tools to do this simple task of serving the Swagger UI, when they are not required.
---
E.g, create a route that serves the base static html file from Swagger [here](https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html). The css/js/image files could also be served from flask, or to make it simple in the documentation they could be linked to someone's hosted files. Line 42 of this file should look something like this:
url: "{{ url_for('serve_swagger_spec') }}",
And the route for this `serve_swagger_spec` can be created like so:
```
spec = APISpec(...)
@app.get('/swagger/spec/')
def serve_swagger_spec():
return jsonify(spec.to_dict()), 200
```
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with Swagger UI's dist/index.html, especially line 42, and the APISpec and Flask route examples in the issue. Done means the documentation gives beginners a clear Flask walkthrough for serving Swagger UI and exposing spec.to_dict() through serve_swagger_spec, with the relevant links.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- flask, python
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100