Add custom schemas to Swagger UI

[igoose1]

Hey!

Is there a way to append schemas which aren't shown in Swagger?

I've coded a trick from #86 to use a complex object in the GET query but a schema I've specified is not in generated Swagger docs as it's not a real Schema for django-ninja, it's just a string field. I had a look at Router and NinjaAPI methods but couldn't find something similar to "add_schema".

[vitalik]

Hi @igoose1

at this moment - you can override the NinjaAPI.get_openapi_schema

class MyApi(NinjaAPI):
    def get_openapi_schema(self, *a, **kw):
        schema = super().get_openapi_schema(*a, **kw)
        schema["paths"]["/foo/bar"]["get"][xxx] = yyy
        return schema

api = MyApi()

[igoose1]

Hi @igoose1

Hi Vitaliy and thanks for your work! It's a neat framework.

at this moment - you can override the `NinjaAPI.get_openapi_schema`

Oh yes, I see. Do you mind about a method in NinjaAPI which simply saves and later appends schemas when `get_openapi_schema` is called? I'm not sure but next days I could code that and give it a try in PR reviewing.

…

-- Oskar Sharipov gpg fingerprint: BAC3 F049 748A D098 A144 BA89 0DC4 EA75 714C 75B5

[stephenrauch]

@igoose1 What do you view as the concern / difference between overriding get_openapi_schema() and instead offering a method for pre-registering some openapi schema to add?

[igoose1]

Hey Stephen! Sorry for a slow response. I was researching the repo and found out a lot details "under the hood" which would help me to implement what you are writing about.

@igoose1 What do you view as the concern / difference between overriding `get_openapi_schema()` and instead offering a method for pre-registering some openapi schema to add?

I like the idea. However, if I understand correctly, right way is to add parameters in every get/post/put/delete of NinjaAPI and Router... Then these parameters must be written in Operation. There are many parameters already and copy-pasting at least 2 lines of code 5 * 2 times doesn't look nice. On the other hand, that's the easiest way and I should try. If you want to code that yourself let me know and go ahead but I'm sure that feature is low-priority :-)

…

-- Oskar Sharipov site (might be unpaid and cancelled): oskarsh.ru e-mail (replace asterisk with dot): oskarsh at riseup * net secondary e-mail (same): oskar * sharipov at tutanota * org gpg fingerprint: BAC3 F049 748A D098 A144 BA89 0DC4 EA75 714C 75B5

[vitalik]

I like the idea. However, if I understand correctly, right way is to add parameters in every get/post/put/delete of NinjaAPI and Router... Then these parameters must be written in Operation. There are many parameters already and copy-pasting at least 2 lines of code 5 * 2 times doesn't look nice.

Hm... then I'm not sure I understand your problem correctly...
maybe you can mock the idea of your application structure ?

you just want extra documentation on OpenAPI/swagger ?

or want to add some common sets of get parameters to multiple operations at once ?

[igoose1]

you just want extra documentation on OpenAPI/swagger ?

That is. That's a made-up example what I want to work: class Padding(Schema): limit: int = 30 offset: int = 0 class Filter(Schema): padding: Padding min_value: int @api.get("/", response=None) def f(request, filter: Filter = Query(...)): pass Swagger UI allows to do a GET request to "http://127.0.0.1:1234/api/?limit=30&offset=0&min_value=123" but it fails with 422: query.filter.padding is missing but required. Then I use json.loads workaround: class Filter(Schema): padding: str = Field(json.dumps(Padding().dict())) min_value: int @validator("padding") def convert_padding(cls, v): return Padding(**json.loads(v)) That works, that doesn't process JSON parsing exceptions but that's not an issue, they are catchable. However, the main problem is that Padding documentation wasn't generated because, de jure, there is no Padding in request parameters, just JSON-formated string.

…

-- Oskar Sharipov site (might be unpaid and cancelled): oskarsh.ru e-mail (replace asterisk with dot): oskarsh at riseup * net secondary e-mail (same): oskar * sharipov at tutanota * org gpg fingerprint: BAC3 F049 748A D098 A144 BA89 0DC4 EA75 714C 75B5

[igoose1]

Github doesn't understand code from mails so that's the whole formatted code in the last step:

import json

from ninja import Field, NinjaAPI, Query, Schema
from pydantic import validator

api = NinjaAPI()


class Padding(Schema):
    limit: int = 30
    offset: int = 0


class Filter(Schema):
    padding: str = Field(json.dumps(Padding().dict()))
    min_value: int

    @validator("padding")
    def convert_padding(cls, v):
        return Padding(**json.loads(v))


@api.get("/", response=None)
def f(request, filter: Filter = Query(...)):
    pass

[igoose1]

Oh, and I forgot to summarize. Yes, I want extra auto-generated documentation of Padding.

maybe you can mock the idea of your application structure ?

An example could be:

@api.get("/", request_parameters={Filter()}, response=None)
def f(request, filter: Filter = Query(...)):
    """
    That GET endpoint mentions `Padding` as that schema's in default `Filter()`.
    As GET request has no body `Padding` docs can be generated at least in "components" in openapi.json.
    """
    pass

That requires inspecting "children" of parameters recursively in order to find every schema. And it's not trivial. That's almost a total support of complex objects in Query.

The issue can be closed as "wontfix".

[igoose1]

And, well, I forgot the aim of the issue again :-/

As auto-generating Query with objects is difficult it's enough to implement api.add_custom_schema which would append a schema in "components" list.