OAS 3.0 schema generation #772

keyz182 · 2020-02-20T17:52:26Z

Fixes #604
Fixes #644

Description of the Change

Extends DRF >= 3.12's generateschema to produce a jsonapi-formatted OAS schema document.
Builds on @n2ygk's work in #689

Updated to latest DJA version

Checklist

PR only contains one change (considered splitting up PR)
unit-test added
documentation updated
CHANGELOG.md updated (only for user relevant changes)
author name in AUTHORS

keyz182 · 2020-02-20T17:54:54Z

There are some TODOs left from @n2ygk's work that I'm unsure of, and/or too unfamiliar to understand. However, for initial support for OAS 3.0, it is working well.

n2ygk · 2020-03-02T23:29:36Z

@keyz182 I will try to take a look at this later this week. Meanwhile, I note there's ongoing activity w.r.t. openapi generateschema happening upstream at DRF including a bit of flaming :-) so you may want to build against DRF-master. (I haven't looked at your work yet, so maybe you are already doing this.)

sliverc

Thanks for picking this up. It will be great to have OAS in DJA. All in all is this PR still very big. I have tried to go through it but I am sure I have overlooked things. So far I haven't looked at the tests yet but just the implementation because of lack of time. Once my comments are addressed I will need to review again anyway.

All in all when you look through the PR again it is important that you could look at:

what code blocks are really necessary for basic OAS support (one comment I have added concerning this but there might be more). All what can be moved to a later PR makes this PR be approved quicker.
update with upstream code. It seems upstream has moved quite a bit and this PR might be simplified therefore (some comments I have added concerning this).

docs/usage.md

example/serializers.py

example/templates/swagger-ui.html

example/tests/test_serializers.py

tox.ini

rest_framework_json_api/schemas/openapi.py

keyz182 · 2020-03-09T09:57:46Z

Thanks for the feedback @sliverc - I'll try to get back and address your comments later this week (I have some other priorities to start this week off).

n2ygk · 2020-04-11T15:23:31Z

FYI DRF 3.12 milestone continues to develop OAS schema definition

Especially useful is this documentation

keyz182 · 2020-04-14T08:28:38Z

Sorry - given current events, and new priorities at work, I'm not going to be able to address your concerns just now @sliverc. I will get back to it though.

auvipy · 2020-07-23T06:02:36Z

Sorry - given current events, and new priorities at work, I'm not going to be able to address your concerns just now @sliverc. I will get back to it though.

hey! can you pick this up again?

auvipy · 2020-07-23T06:36:17Z

I will try to handle it if no one got the time. will try to split the PR in smaller chunks

keyz182 · 2020-07-23T08:39:05Z

Sorry - given current events, and new priorities at work, I'm not going to be able to address your concerns just now @sliverc. I will get back to it though.

hey! can you pick this up again?

@auvipy Sorry, I'm not going to have time for a few months at least unfortunately :(

If you want to take over, I'm happy to give pointers where I can.

auvipy · 2020-07-23T09:30:42Z

OK I will take this over and feel free to review.

n2ygk · 2020-07-29T21:10:46Z

I've just had a quick look at current drf master (still pre-3.12) and have noticed a few things that might impact this code if not already dealt with:

many private methods are now public (remove the _). The private versions are still there but will raise a warning.
DRF now implements components and has a few other changes in get_schema() but it looks like it still has to be fully overridden because of the need to "expand" endpoints for relationship and related views. An idea for a future PR to DRF might be to add a method that can be more cleanly extended.

n2ygk · 2020-08-03T20:11:32Z

FYI - I've got some free time this week so started looking at this, especially w.r.t. changes to upstream DRF and will be pushing a rebase shortly.

auvipy · 2020-08-04T09:36:28Z

FYI - I've got some free time this week so started looking at this, especially w.r.t. changes to upstream DRF and will be pushing a rebase shortly.

Thats great! Looking forwarded to it

n2ygk · 2020-08-07T00:27:09Z

working my way backwards from master through earlier versions of DRF to eventually get tox tests to conditionalize as appropriate and otherwise run cleanly.

n2ygk · 2020-08-07T17:45:33Z

See also PR #804 which I've copied the change over here just to keep this moving and cleanly rebaseable.

codecov · 2020-08-07T17:50:09Z

Codecov Report

Merging #772 into master will increase coverage by 0.10%.
The diff coverage is 98.82%.

@@            Coverage Diff             @@
##           master     #772      +/-   ##
==========================================
+ Coverage   97.77%   97.87%   +0.10%     
==========================================
  Files          58       62       +4     
  Lines        3104     3443     +339     
==========================================
+ Hits         3035     3370     +335     
- Misses         69       73       +4

Impacted Files	Coverage Δ
example/settings/dev.py	`100.00% <ø> (ø)`
rest_framework_json_api/schemas/openapi.py	`98.21% <98.21%> (ø)`
example/tests/snapshots/snap_test_openapi.py	`100.00% <100.00%> (ø)`
example/tests/test_format_keys.py	`100.00% <100.00%> (ø)`
example/tests/test_openapi.py	`100.00% <100.00%> (ø)`
example/tests/unit/test_filter_schema_params.py	`100.00% <100.00%> (ø)`
rest_framework_json_api/django_filters/backends.py	`100.00% <100.00%> (ø)`
... and 1 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b192cb0...af5f4ea. Read the comment docs.

sliverc · 2020-08-19T14:35:15Z

I won't have the time right now to closely look at this as in DRF there has been many changes and this is a fairly large PR.

@n2ygk I guess you won't see this as ready though right? As there are quite a few TODOs in the code. And possibly as there are many changes in DRF we should properly also wait till 3.12 is released.

n2ygk · 2020-08-19T16:20:38Z

No, still a draft. I have to check out a few more items and fix them to align with DRF 3.12.

…

On Wed, Aug 19, 2020 at 10:35 AM Oliver Sauder ***@***.***> wrote: I won't have the time right now to closely look at this as in DRF there has been many changes and this is a fairly large PR. @n2ygk <https://github.com/n2ygk> I guess you won't see this as ready though right? As there are quite a few TODOs in the code. And possibly as there are many changes in DRF we should properly also wait till 3.12 is released. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#772 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABBHS5Z4UJSV6RYMSN52VHTSBPPLHANCNFSM4KYT2BNQ> .

n2ygk · 2020-08-21T01:25:26Z

This is getting closer to reviewable. I'll do another rebase when I'm ready and will then request your review.

n2ygk

Things I still need to do before a final review request:

Check on Oliver's remaining open review comments
See if SchemaGenerator.schema_init might be included in upstream DRF.
Decide what TODOs can be deferred for now vs. must haves.

tox.ini

rest_framework_json_api/schemas/openapi.py

sliverc · 2020-10-14T20:41:38Z

@n2ygk went through the conversations and marked the once solved which are. Besides the relationship issue there are also some conversations though which you might have overlooked.
When you go to #772 (review) there is a link "7 hidden conversations Load more..." which I assume you did not see?

n2ygk · 2020-10-15T19:48:16Z

@sliverc please hold off on further review until I solve #772 (comment)

sliverc · 2020-10-23T13:51:23Z

@n2ygk Do you think you will get to the open OAS issues in the next few days?

If not once #846 is merged I would be fine if we release 4.0.0 nowish (mainly to support newest DRF version) and postpone this to the next minor version 4.1.0 as it is fully backwards compatible. What do you think?

n2ygk · 2020-10-23T14:10:41Z

Yes I think I have a solution for that problem I was working

…

On Fri, Oct 23, 2020 at 9:51 AM Oliver Sauder ***@***.***> wrote: @n2ygk <https://github.com/n2ygk> Do you think you will get to the open OAS issues in the next few days? If not once #846 <#846> is merged I would be fine if we release 4.0.0 nowish (mainly to support newest DRF version) and postpone this to the next minor version 4.1.0 as it is fully backwards compatible. What do you think? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#772 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABBHS57UUIM2YQK2XAZP2YTSMGC6XANCNFSM4KYT2BNQ> .

- <typename> gets added e.g. in swagger-ui and breaks queries

is merged

This reverts commit 5855b65.

Improve comment describing the need to monkey-patch view.action.

n2ygk · 2020-10-24T12:49:47Z

@sliverc Ready for your review.

sliverc · 2020-10-29T16:15:46Z

Thanks for your work on this! This now looks good as a start and can be vetted as it is used more widely.

keyz182 · 2020-10-29T16:18:48Z

Nice work @n2ygk !

n2ygk · 2020-10-29T18:30:17Z

@sliverc It looks like travis has stalled.

n2ygk · 2020-10-29T21:03:29Z

@sliverc It looks like travis has stalled.

Not stalled but running really slowly. So far 3+ hours in and not done yet.

n2ygk · 2020-10-29T22:08:01Z

@sliverc It looks like travis has stalled.

Not stalled but running really slowly. So far 3+ hours in and not done yet.

Hmm, this tweet says something about .org vs. .com

keyz182 requested a review from sliverc February 20, 2020 17:55

sliverc mentioned this pull request Mar 8, 2020

initial implementation of OAS 3.0 generateschema #689

Closed

5 tasks

sliverc changed the title ~~Continuation of #689 - OAS 3.0 schema generation~~ OAS 3.0 schema generation Mar 8, 2020

sliverc previously requested changes Mar 8, 2020

View reviewed changes

mcovalt mentioned this pull request Mar 19, 2020

API Documentation Chemical-Curation/chemcurator_django#75

Closed

n2ygk force-pushed the openapi_schema branch from 8823151 to 20c4d8a Compare July 31, 2020 22:11

n2ygk force-pushed the openapi_schema branch 3 times, most recently from 0f05799 to b4c37c1 Compare August 7, 2020 00:25

n2ygk force-pushed the openapi_schema branch from 7eada08 to 941a84b Compare August 21, 2020 20:17

n2ygk requested changes Aug 21, 2020

View reviewed changes

tox.ini Outdated Show resolved Hide resolved

rest_framework_json_api/schemas/openapi.py Outdated Show resolved Hide resolved

rest_framework_json_api/schemas/openapi.py Outdated Show resolved Hide resolved

n2ygk force-pushed the openapi_schema branch from 941a84b to 07034ae Compare August 25, 2020 17:58

n2ygk force-pushed the openapi_schema branch from 7fa5ee0 to be2340a Compare October 14, 2020 16:05

n2ygk added 15 commits October 23, 2020 16:41

initial implementation of OAS 3.0 generateschema

9efea6a

my security schemes PR didn't make it into DRF 3.12

e715638

remove fields deepObject placeholder

28be828

- <typename> gets added e.g. in swagger-ui and breaks queries

make it clear this is an initial openapi release

de2bece

getattr for improved readability

8273f48

remove security objects until upstream encode/django-rest-framework#7516

ae223d4

is merged

no need for duplicated snapshots exclusion

abd9c51

DRF 3.12 is now the minimum

61c27e0

use pytest style: remove superfluous TestBase

c8ea923

copy() not necessary

5594691

simplify relationships paths

0ea816e

Revert "simplify relationships paths"

71777da

This reverts commit 5855b65.

documentation corrections for openapi

7a6a088

rename mutable private methods and improve their docstrings

407e119

Fix RelationshipView.

bb905bf

Improve comment describing the need to monkey-patch view.action.

n2ygk force-pushed the openapi_schema branch from 6fccbaa to bb905bf Compare October 23, 2020 20:43

Merge branch 'master' into openapi_schema

af5f4ea

sliverc approved these changes Oct 29, 2020

View reviewed changes

sliverc merged commit 9113ca0 into django-json-api:master Oct 30, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OAS 3.0 schema generation #772

OAS 3.0 schema generation #772

keyz182 commented Feb 20, 2020 •

edited by sliverc

Loading

keyz182 commented Feb 20, 2020

n2ygk commented Mar 2, 2020

sliverc left a comment

keyz182 commented Mar 9, 2020

n2ygk commented Apr 11, 2020 •

edited

Loading

keyz182 commented Apr 14, 2020

auvipy commented Jul 23, 2020

auvipy commented Jul 23, 2020

keyz182 commented Jul 23, 2020

auvipy commented Jul 23, 2020

n2ygk commented Jul 29, 2020

n2ygk commented Aug 3, 2020

auvipy commented Aug 4, 2020

n2ygk commented Aug 7, 2020

n2ygk commented Aug 7, 2020

codecov bot commented Aug 7, 2020 •

edited

Loading

sliverc commented Aug 19, 2020

n2ygk commented Aug 19, 2020 via email

n2ygk commented Aug 21, 2020

n2ygk left a comment

sliverc commented Oct 14, 2020

n2ygk commented Oct 15, 2020

sliverc commented Oct 23, 2020

n2ygk commented Oct 23, 2020 via email

n2ygk commented Oct 24, 2020

sliverc commented Oct 29, 2020

keyz182 commented Oct 29, 2020

n2ygk commented Oct 29, 2020

n2ygk commented Oct 29, 2020

n2ygk commented Oct 29, 2020

OAS 3.0 schema generation #772

OAS 3.0 schema generation #772

Conversation

keyz182 commented Feb 20, 2020 • edited by sliverc Loading

Description of the Change

Checklist

keyz182 commented Feb 20, 2020

n2ygk commented Mar 2, 2020

sliverc left a comment

Choose a reason for hiding this comment

keyz182 commented Mar 9, 2020

n2ygk commented Apr 11, 2020 • edited Loading

keyz182 commented Apr 14, 2020

auvipy commented Jul 23, 2020

auvipy commented Jul 23, 2020

keyz182 commented Jul 23, 2020

auvipy commented Jul 23, 2020

n2ygk commented Jul 29, 2020

n2ygk commented Aug 3, 2020

auvipy commented Aug 4, 2020

n2ygk commented Aug 7, 2020

n2ygk commented Aug 7, 2020

codecov bot commented Aug 7, 2020 • edited Loading

Codecov Report

sliverc commented Aug 19, 2020

n2ygk commented Aug 19, 2020 via email

n2ygk commented Aug 21, 2020

n2ygk left a comment

Choose a reason for hiding this comment

sliverc commented Oct 14, 2020

n2ygk commented Oct 15, 2020

sliverc commented Oct 23, 2020

n2ygk commented Oct 23, 2020 via email

n2ygk commented Oct 24, 2020

sliverc commented Oct 29, 2020

keyz182 commented Oct 29, 2020

n2ygk commented Oct 29, 2020

n2ygk commented Oct 29, 2020

n2ygk commented Oct 29, 2020

keyz182 commented Feb 20, 2020 •

edited by sliverc

Loading

n2ygk commented Apr 11, 2020 •

edited

Loading

codecov bot commented Aug 7, 2020 •

edited

Loading