marshmallow-code / marshmallow-code/apispec

Documentation to explitly specify how to serve Swagger UI using apisec ?

Open Beginner friendly
#750 1 comment 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.