Chalice: More complex Swagger ability?

[noahgift]

Hi,

Do you have any plans to support more complex Swagger configurations, something like this: https://github.com/rochacbruno/flasgger, etc? If not, how are people currently supplementing their swagger api docs.

Thanks!

[JordonPhillips]

I think it would be a really good idea to extract python doc strings as apigateway docs. That would make them immediately available in the swagger exports, in addition to any other apigateway features. So the following code:

from chalice import Chalice

app = Chalice(app_name="documentation-as-a-service")


@app.route("/")
def index():
    """This doc string would be added to apigateway."""
    return {'hello': 'world'}

Would automatically have the documentation for the base route set as "This doc string would be added to apigateway."

Is that the sort of thing you're looking for?

[noahgift]

Exactly! Almost considering writing it myself, but didn't want to have a fork that conflicted.

[RobertAtomic]

@JordonPhillips Do you guys accept PRs for stuff like this? We're just getting started with a chalice based project and we're trying to decide if we implement a sidecar process to generate more robust swagger, or if we fork chalice and implement there. We don't like the fork option unless there's some expectation that it might get merged.

[JordonPhillips]

@RobertAtomic we sure do! You can find our contributor guide here.

[dmulter]

I've added the following code that I believe should handle adding Summary and Description in the swagger output (deploy/swagger.py). Unfortunately I can't seem to figure out how to get these lines to actually execute, so I can't verify the code. It doesn't seem to walk all paths every time I do a deploy. Hopefully someone can take the next step based on the code below. The 5 new lines are right after initialization of the base current dict.

    def _generate_route_method(self, view):
        # type: (RouteEntry) -> Dict[str, Any]
        current = {
            'consumes': view.content_types,
            'produces': ['application/json'],
            'responses': self._generate_precanned_responses(),
            'x-amazon-apigateway-integration': self._generate_apig_integ(
                view),
        }  # type: Dict[str, Any]
        if view.view_function.__doc__:
            doc_lines = view.view_function.__doc__.splitlines()
            current['summary'] = doc_lines[0]
            if doc_lines[1]:
                current['description'] = '\n'.join(doc_lines[1:])
        if view.api_key_required:
            # When this happens we also have to add the relevant portions
            # to the security definitions.  We have to someone indicate
            # this because this neeeds to be added to the global config
            # file.
            current.setdefault('security', []).append({'api_key': []})
        if view.authorizer:
            current.setdefault('security', []).append(
                {view.authorizer.name: []})
        if view.view_args:
            self._add_view_args(current, view.view_args)
        return current

[dmulter]

Ok, I found the problem in my code above. It appears that there must be a try/except block at a high level when doing the deploy, as the code threw an IndexError and just silently stopped. I will put up a PR shortly that adds setting of the Swagger 'summary' and 'description' fields for each route based on the docstring.

I'm also thinking of submitting another PR that adds the ability to tag routes. It's super useful to generate docs that have a description for the resource. Watch for that soon after.

[dmulter]

I think I'll break out the Swagger tags support to a new issue...

[jamesls]

https://github.com/aws/chalice/pull/681 is now merged.