Hi,

I have a Flask app using Blueprints and would like to document the API using swagger. I love the idea of having a single source of truth when it comes to the API documentation and hence would like to use flask-swagger. Does it support Blueprint ? I must admit I didn't even try, I was hoping to first get some tips before messing around with my docstrings everywhere....

thanks

Brieuc

Permutations of routes and methods appear as documented operations in the swagger output that aren't present in the code. Other applications rely on the JSON output of swagger, and the superfluity of operations breaks that.

mod.add_url_rule('/edges/', defaults={'annotation_id': None}, methods=['GET']) mod.add_url_rule('/edges/', methods=['POST']) mod.add_url_rule('/edges/<int:annotation_id>/', methods=['GET', 'PUT', 'PATCH', 'DELETE'])

i.e. The code defines a route at /edges/ with "GET" and "POST" methods. The code also defines a route at /edges/<int:annotation_id>/ with "GET", "PUT", "PATCH", and "DELETE" methods. [This is a total of 2 routes and 5 method verbs.] The swagger output shows a list of 10 operations, which includes combinations of verbs and routes that don't exist in code (e.g. "POST" for the /edges/<int:annotation_id>/ route, and "PUT" for the /edges/ route).

To use markdown in my api docs, right now I use monkey patching like this:

import flask_swagger
import CommonMark

def sanitize(text):
    parser = CommonMark.DocParser()
    renderer = CommonMark.HTMLRenderer()
    ast = parser.parse(text)
    return renderer.render(ast)

flask_swagger._sanitize = sanitize

But this could be made a configurable parameter like:

def swagger(app, process_doc=_sanitize):
    ...

You can now specify base path for yml files:

app = Flask(__name__)

@app.route("/spec")
def spec():
    base_path = os.path.join(app.root_path, 'docs')
    return jsonify(swagger(app), from_file_keyword="swagger_from_file", base_path=base_path)

and use relative pathes:

@app.route('/test', methods=['POST'])
def login():
    """
    swagger_from_file: test.yml
    """

Hi there,

I currently have a flask_restful Resource with 2 path parameters: one compulsory, and one optional. I followed this recommendations of writing it this way:

api.add_resource(ProductsResource, '/products/<string:slug>', '/products/<string:slug>/<string:color>')

class ProductsResource(Resource):
      @marshal_with(products_fields)
      def get(self, slug, color=None):
           ....

Then, i have the following YML documentation in the docstring regarding parameters:

...
- name: slug
   in: path
   description: product's slug
   type: string
   required: true
- name: color
   in: path
   description: product's color
   type: string
   required: true

When I go to my project on http://localhost:5000/spec, I see that I have 2 endpoint generated:

• http://localhost:5000/products/{slug}
• http://localhost:5000/products/{slug}/{color}

But, for both endpoints there are those 2 required parameters, resulting in a swagger error: Path parameter is defined but is not declared: color.

Do you think it would be possible to filter the path parameters based on the endpoints used ? Here it would mean filter out 'color' for the first endpoint.

Thanks, Pierre.

• The following path is listed in docs as: https://api.getsling.com/#/timeclock/post_timeclock_clockin
• This path is for clocking in for shifts, but it is wrong.
• The valid path for proper documentation changes by the following:

Old Path: /timeclock/clockin
New path: /{org_id}/timeclock/clockin

When running flaskswagger, the run() function would be invoked twice: One from the entrypoint and another by just importing build_swagger_spec.

This ensures the spec is only dumped once to stdout.

Hi, I installed flask-swagger using 'pip install flask-swagger' and I noticed the downloaded source code is different from the one published in the master branch. Notice "_parse_docstring" function on the left and "_find_from_file" on the right.

Maybe I'm doing something wrong and I haven't realize it, any thoughts?

Hi,

This is a proposal to decode a special line in a docstring swagger_from_file: path.

I think it could be useful sometimes to take the yaml swagger spec out of the docstring:

• if you have other things to say in the docstring,
• if it's easier to edit yaml code from a .yml file.

In the pull request you'll find besides flask_swagger.py a modified example and README.md

Please criticize as needed. Thanks.

If you will try to use jsonschema`s Draft4Validator to validate swagger.json, generated by flask-swagger, then will discover it is failing, trying to match numerical HTTP status codes from responses agains this piece of Swagger 2.0 spec:

"responses": {
  "type": "object",
  "description": "Response objects names can either be any valid
  HTTP status code or 'default'.",
  "minProperties": 1,
  "additionalProperties": false,
  "patternProperties": {
    "^([0-9]{3})$|^(default)$": {
      "$ref": "#/definitions/responseValue"
    },
    "^x-": {
      "$ref": "#/definitions/vendorExtension"
    }
  }
}

This fix just coerse responses keys to strings.

Currently it is not possible to define definitions within the properties or items (if within an array) of other definitions.

This change recursively traverses the properties of definitions to find other schema defs. This is a deviation from the standard, but the cleanest way I could think to handle it.

Also builds on the work by abhaga to handle multiple views for same route. Handles the case where definitions get overridden by separate view functions for the same verb.

This PR adds an optional ability to embed plantuml diagrams in the description section of endpoint docstrings. Example:

@app.route('/foo')
def foo():
    """
    # Expected sequence
    @startuml
    client -> server: /foo
    server --> client: response {id}
    client -> server: /bar/{id}
    @enduml
    """
    return 'foobar'

This relies on having a PlantUML server available. By default, it uses the public server available at http://www.plantuml.com/plantuml/img/ but this can be configured by setting FLASK_SWAGGER_PLANTUML_SERVER in the flask app config.

The diagrams it generates go into a subdirectory of the app's static content directory. By default this subdirectory is called uml but it can be configured by setting FLASK_SWAGGER_PLANTUML_FOLDER in the flask app config.

The diagram content is replaced with a GFM image tag. If an error occurs while generating the image, the image content is replaced with an error message. If the plantuml package is not available, swagger generation proceeds as normal.

I've also added parameters to the swagger method for title, version and description. This is mostly so that the description content can be scanned for diagram content.

Currently uses some Python 3.6+ syntax. Let me know if this is an obstacle to merging & I can fix.

This PR adds some logging so that errors in the YAML in a docstring give some indication of which method caused the problem. Several times now I've gone over a large codebase adding swagger docstrings then tried to view the documentation, only to find that there is an error - somewhere. The YAML parser will tell you which line of a docstring the error happened on, and might tell you what the offending content was, and that might be enough to find the error. Or it might not. This logs which object the docstring appeared on.

I'm using flask-swagger-0.2.14 but when i ran the first example like in your README.md

@app.route("/spec")
def spec():
   base_path = os.path.join(app.root_path, 'docs')
   return jsonify(swagger(app), from_file_keyword="swagger_from_file", base_path=base_path)

@app.route('/test', methods=['POST'])
def login():
   """
   swagger_from_file: test.yml
   """

I got this error

swagger() got an unexpected keyword argument 'base_path'

Could you tell me how to resolve it! Thank in advance!

I am using Flask-Swagger with Flask-MongoRest. Last versions, with Python 3.8.2.

I wanted to simply try this code from the README:

from flask import Flask, jsonify
from flask_swagger import swagger

app = Flask(__name__)

@app.route("/spec")
def spec():
    return jsonify(swagger(app))

then when I do GET http://127.0.0.1:5000/spec, the following error is displayed:

  File "/home/cedric/.cache/pypoetry/virtualenvs/stats-api-7Yf7ZOUq-py3.8/lib/python3.8/site-packages/flask_swagger.py", line 178, in <lambda>
    and verb in map(lambda m: m.lower(), endpoint.methods) \
AttributeError: type object 'Create' has no attribute 'lower'

I fixed my issue by changing this code: https://github.com/gangverk/flask-swagger/blob/master/flask_swagger.py#L177-L179

to

if hasattr(endpoint, 'methods') \
                    and verb in map(lambda m: m.method.lower(), endpoint.methods) \	
                    and hasattr(endpoint.view_class, verb):

Since actually here m is an object, not a string. m.method is a string. It also works with str(m).lower().

With this change, it works quite well.

If you want I can create a fix which will works with m.lower() and m.method.lower() and make a pull request.

Or do you thing the issue is on the side of Flask-MongoRest ?