Integrate swagger

[josejachuf]

These days I was watching FastApi and I really liked the self-documentation. I have these doubts: 1) How complicated can it be to integrate Swagger into emmett-rest? 2) If it were integrated, would it be through an extension? Best regards Jose

[gi0baro]

@josejachuf before answering your question, let me say I have no experience with swagger and also I'm not a big fan of it: I generally prefer static, well-written api docs (eg: https://stripe.com/docs/api, https://developers.asana.com/docs) so I would probably prefer integrating tools like https://github.com/slatedocs/slate. But I'm not against swagger, I will surely merge a PR which integrates it.

So, to answer your questions:

• I have no idea. Theoretically speaking I think extracting details from serializers and parsers to configure swagger might be enough, but as I said I never used it
• I think it can be part of the rest extension, no need to create a separate one

[delarroqua]

Hello @gi0baro, and thank you for your answer above !

I used Emmett (which is really great btw) to create an API, and I would like to generate API Docs. If not Swagger, what tool could I use to generate a Doc for my Emmett App ?

Thank you !

[gi0baro]

If not Swagger, what tool could I use to generate a Doc for my Emmett App ?

Hi @PierreDelarroqua, unfortunately at the moment there is no quick solution for that. I'm trying to develop a static documentation generator, but I have no ETA at the moment – it's kind a busy moment.

I still will accept a PR from anybody out there that will provide integration for an external tool; at the moment I'm just not able to do it by myself.

[josejachuf]

Hi @gi0baro. What good news the incorporation of the Doc de openapi. Thanks for your works.

I'm trying to try but I do not know where it comes from docs_module

My hierarchy of modules is:

app.api.v1.foo

up to v1 all are AppModule, then foo is RESTModule

then I tried:

docs = foo.docs_module( name, "api_docs", title="My APIs", version="1", modules_tree_prefix="api.v1" )

docs = foo.docs_module( AttributeError: 'RESTModule' object has no attribute 'docs_module'

How would this be?

Jose

[gi0baro]

@josejachuf the docs_module is a method of the REST extension. When you initialise the extension you can store the instance in a variable:

rest = app.use_extension(REST)

and then convert your code to:

docs = rest.docs_module(
    __name__,
    "api_docs",
    title="My APIs",
    version="1",
    modules_tree_prefix="api.v1"
)

[josejachuf]

Thanks, This works fine!

A query, this generates json and yaml, not html?

[gi0baro]

@josejachuf the module exposes the json and yaml schema under {url_prefix}/openapi.{json|yaml} and the UI under the ui_path parameter of the docs_module (default is {prefix}/docs). Mind that the expose_ui parameter under default behaviour use the debug flag of your application, if you want to always expose the UI set that parameter to True.

[josejachuf]

perfect, thank you very much