Skip to content

adding drf-yasg to the documentation's documenting-your-api section #5719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from

Conversation

fazpu
Copy link

@fazpu fazpu commented Jan 1, 2018

Should solve #5718.

@fazpu fazpu force-pushed the api_documentation_drf_yasg branch from 16cb272 to eefd5a7 Compare January 1, 2018 20:00
Copy link
Collaborator

@carltongibson carltongibson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy to add a link to the drf-yasg package here, but not happy with the particular text.

  1. It need to focus on drf-yasg features without the criticism of other packages, in part because...
  2. The planned changes for 3.8 should invalidate most of what's said here, so as written it won't age well.

Something just stating that drf-yasg allows response schema generation etc would be sufficient.

@axnsan12
Copy link
Contributor

axnsan12 commented Jan 2, 2018

@fazpu thank you for the kind words! 😄

@carltongibson I think as the maintainer of the package in question I should step forward and write a PR for this - getting on that

Also, I'd be curios about the planned 3.8 changes you are talking about - is OpenAPI support planned, or are there incoming changes to Core API to enable handling of this?

And on the same line of thought, I was always curios why it was decided to create a new format instead of using an already existing one (be it OpenAPI or whatever else) - is there anywhere I could read about that?

@carltongibson
Copy link
Collaborator

carltongibson commented Jan 2, 2018

@axnsan12 Thanks (again) for the input.

And on the same line of thought, I was always curios why it was decided to create a new format instead of using an already existing one (be it OpenAPI or whatever else) - is there anywhere I could read about that?

It's just a history thing really. At the time there were a number of competing description formats; it wasn't clear that Swagger would be the winner in that space. Core API is not a format so much as a format neutral way of modelling the domain: the format would be Core JSON but, renderers allow outputting to whatever format you like, Swagger, API Blueprint, HAL, etc.

(Core API also has an interest in Hypermedia that we won't go into now.)

Fast forward and Open API is the current champion in the description space so we need to up our game there.

Exactly what that entails for v3.8 we need to see. (Part of that is a review on the Third-Party packages, including drf-yasg, to see where our effort is best spent.)

@carltongibson
Copy link
Collaborator

carltongibson commented Jan 19, 2018

Update: It looks like we'll roll a maintenance 3.8 (with small BC changes prompting the minor release).

The feature work will then be 3.9. (It's not forgotten: it's just numbers are cheap.)

@axnsan12: You asked somewhere (I can't find it now) about extra API on APIView, for something like get_schema_class.

The answer to that is that I'd (still) rather back-inject that from a custom view descriptor than add it to the APIView API (which is already big enough; schemas are separate, and we want to keep it that way).

So you might do something like:

class CustomViewDescriptor():

    def __get__(self, instance, owner):
            inspector_class = instance.get_schema_class()
            inspector = inspector_class()
            inspector.view = instance
            return inspector

    ...

Note: I don't think I'd do this personally.

Here you have access to method, action and all the rest. The only thing not passed is the routed path, but I'd argue you're in big trouble if your choice of schema generator class depends on that... (Even then, the SchemaGenerator could make that available to the view before fetching the schema if it was really necessary.)

I'm pretty sure the API is sufficient to cover whatever use-cases. I'm open to the possibility of a change of course. But I'd rather steer this way. (APIView really is big enough already.)

I hope that makes sense.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy