OpenAPI models from python typing

[Sytten]

It would nice to be able to generate models from the Typing for Swagger/OpenAPI instead of the empty model currently used.

[jamesls]

Could you elaborate a little more on how you see this working? Some example code/swagger docs would be helpful. Thanks!

[Sytten]

Sure! Let's take a simple case:

class MyModel(NamedTuple):
    hello: str

@app.route("/")
def index() -> MyModel:
    return MyModel("world")

This could generate the following OpenAPI:

paths:
  /:
    get:
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/MyModel"
definitions:
  MyModel:
    type: "object"
    properties:
      hello:
        type: "string"

We should also use the same principle for the params and the body (if possible, but it would be harder since we don't have it as a param).

Maybe something easier for a first step would be to support the documentation as a docstring like what https://github.com/rochacbruno/flasgger does. We already support summary. We should also document this since I didn't see anything related to it.

[jamesls]

Ah I see, that's pretty interesting. Thanks for the suggestion, marking as a feature request.

[dragon788]

Is this already covered by something like https://pypi.org/project/apispec-chalice/ ?

[ricky-sb]

@dragon788, no, that forces you to write a separate set of docs. To quote FastAPI's docs:

The way it works is that you write the definition of the schema using YAML format inside the docstring of each function handling a route.

But then, we have again the problem of having a micro-syntax, inside of a Python string (a big YAML).

The editor can't help much with that. And if we modify parameters or Marshmallow schemas and forget to also modify that YAML docstring, the generated schema would be obsolete.

[zygopleural]

Hey, any update on this?

[knowsuchagency]

Found an interesting project related to this issue: https://github.com/TestBoxLab/chalice-spec

shoutout to @jakemwood I'm excited to try it out!

[knowsuchagency]

I wrote a simple gist adding a /docs endpoint to a chalice app using chalice-spec https://gist.github.com/knowsuchagency/8307980a51ee2d400f4d9271dc88942f

[Mexflubber]

Upvoting for this to be native support ! chalice-spec does not support everything in chalice, for example it's unknown if it works with blueprints

I wrote a simple gist adding a /docs endpoint to a chalice app using chalice-spec https://gist.github.com/knowsuchagency/8307980a51ee2d400f4d9271dc88942f