No way to document parameters

[leonardoarroyo]

New django-rest-swagger versions have deprecated YAML docstrings. There's no documentation demonstrating how to document request fields anymore.

There's some things you can do by changing the filter_backends on ViewSets, for example, but it just doesn't feel right.
I still haven't found a way to do this on function based views.

[ameade]

It also seems that coreapi is less descriptive than openapi so the openapi schema will be incomplete since we generate from rest_frameworks coreapi document (via https://github.com/core-api/python-openapi-codec). I need the ability to specify response codes and bodies. IIUC the old way to get around this was with YAML docstrings but those are deprecated.

[daimon99]

I still do not know how to document parameters.
Hope there will be an example in the tutorial app.
for example, how to document the parameters(mobile) in the method sendcode?

class UserViewSet(mixins.CreateModelMixin,
                  mixins.RetrieveModelMixin,
                  mixins.UpdateModelMixin,
                  viewsets.GenericViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = (IsUserOrReadOnly, IsAuthenticated)

    @list_route(methods=['post'])
    def sendcode(self, request):
        """send verify code"""
        from moore.services.yimei import send_sms

        username = request.data.get('mobile')
        verifycode = random.randint(1000, 9999)
        send_sms(username, verifycode)
        return Response('data': 'send ok')

[daimon99]

I write a custom schemagenerator to deal with parameter:

class SchemaGenerator(schemas.SchemaGenerator):
    def get_link(self, path, method, callback, view):
        """Custom the coreapi using the func.__doc__ .

        if __doc__ of the function exsit, use the __doc__ building the coreapi. else use the default serializer.

        __doc__ in yaml format, eg:

        desc: the desc of this api.
        ret: when success invoked, return xxxx
        err: when error occured, return xxxx
        input:
        - name: mobile
          desc: the mobile number
          type: string
          required: true
          location: form
        - name: promotion
          desc: the activity id
          type: int
          required: true
          location: form
        """
        fields = self.get_path_fields(path, method, callback, view)
        yaml_doc = None
        func = getattr(view, view.action) if getattr(view, 'action', None) else None
        if func and func.__doc__:
            try:
                yaml_doc = yaml.load(func.__doc__)
            except:
                yaml_doc = None
        if yaml_doc and 'desc' in yaml_doc:
            desc = yaml_doc.get('desc', '')
            ret = yaml_doc.get('ret', '')
            err = yaml_doc.get('err', '')
            _method_desc = desc + '<br>' + 'return: ' + ret + '<br>' + 'error: ' + err
            params = yaml_doc.get('input', [])
            for i in params:
                _name = i.get('name')
                _desc = i.get('desc')
                _required = i.get('required', True)
                _type = i.get('type', 'string')
                _location = i.get('location', 'form')
                field = coreapi.Field(
                    name=_name,
                    location=_location,
                    required=_required,
                    description=_desc,
                    type=_type
                )
                fields.append(field)
        else:
            _method_desc = func.__doc__ if func and func.__doc__ else ''
            fields += self.get_serializer_fields(path, method, callback, view)
        fields += self.get_pagination_fields(path, method, callback, view)
        fields += self.get_filter_fields(path, method, callback, view)

        if fields and any([field.location in ('form', 'body') for field in fields]):
            encoding = self.get_encoding(path, method, callback, view)
        else:
            encoding = None

        if self.url and path.startswith('/'):
            path = path[1:]

        return coreapi.Link(
            url=urlparse.urljoin(self.url, path),
            action=method.lower(),
            encoding=encoding,
            fields=fields,
            description=_method_desc
        )

[leonardoarroyo]

@daimon99, on list routes, you can set the filter_backends property on the ViewSet to correctly generate the schema, still it feels a little hacky.

[daimon99]

just wait rest framework 3.5. tomchristie said: "Gothca, understand the issue now! Yes, this has been an issue in how we generate the schema for swagger UI. It's resolved as part of the upcoming 3.5 release."

[daimon99]

encode/django-rest-framework#4241.

[psychok7]

So no updates yet regarding this issue??

[kevin-brown]

Given that the 3.5 release is out, has this ticket been handled?

[angvp]

Maybe mentioning @tomchristie ?

[tomchristie]

There's some level of support for this, but it's a little patchy.

You'd need to look at the implementation of get_link() to see how the fields are built up. The description attribute on fields can then be pulled out by the swagger UI renderer...

• Serializer fields (request body/form) have the help_text attribute pulled into the description.
• Filter fields and pagination fields (query params) have whatever get_schema_fields returns (currently I don't think that the various get_schema_fields() implementations populate any field descriptions, tho you could override the get_schema_fields() method using a custom filter/paginator class)
• URL path fields have no way of setting a description.

[slykar]

Does CoreAPI even support custom type definition? I know you can specify anything in the field.type.

I think you would need to change rest_framework_swagger.renderers.OpenAPICodec so that the returned Swagger object would be extended with definitions:.

Those definitions could be based on Serializers and pushed to coreapi.document.Document with SchemaGenerator maybe.
The coreapi.document.Document seem to be accepting any data.

class Document(itypes.Dict):
    # ...
    self._data = {key: _to_immutable(value) for key, value in content.items()}

[tomchristie]

@slykar - I think you're mixing up different concerns in that comment. (What datatypes can be included in a Document, vs. how do we describe parameter help text and parameter types.

I'm currently working on a documentation generator to tie in with Core API, which is helping tease out some of the docs related requirements. I'd suggest we hold further discussion until we can use that as a starting point.

Aside: Also worth re-iterating that I want to see any spec changes to Core API be driven by very explicit tooling requirements. Eg. "Adding X to Core API will allow me to do Y".

[slykar]

@tomchristie - To give some background. What I was trying to achieve was a documentation of profile parameter on my endpoint, which is an embedded document with it's own schema. SchemaGenerator specifies the type as 'object', where it should be a type on it's own, like 'UserProfile'.

When using OpenAPI, you can document such field by setting custom type. In OpenAPI this type is defined by definitions section. This is something you can not do with CoreAPI as far as I know, even tough the CoreAPI Field.type takes arbitrary string and you could put 'UserProfile' there.

The spec mismatch makes it hard to properly document endpoint parameters, utilizing OpenAPI type definitions. This is something I require, otherwise the generated OpenAPI spec is worthless for me.

I was even trying to figure out how to push this type information through SchemaGenerator to CoreAPI to OpenAPI.

Right now I'm back to writing the OpenAPI spec file by hand.

[tomchristie]

Gotcha. And yes, we may well move towards allowing for annotation information about more complex types. Out of interest what tooling are you using to document the API - Swagger UI, or something else?

[slykar]

@tomchristie I'm using Swagger UI, tough, when writing spec by hand I write it using API Blueprint (IMO easier to write and read than OpenAPI), then convert it to OpenAPI spec for Swagger UI.