Skip to content
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

Add support for API documentation #323

Open
wants to merge 2 commits into
base: python3
Choose a base branch
from

Conversation

Ugtan
Copy link
Collaborator

@Ugtan Ugtan commented Aug 11, 2021

This PR adds support for API documentation with the help of drf-yasg library.

@rtgdk
Copy link
Collaborator

rtgdk commented Aug 15, 2021

@Ugtan How will this generate swagger specs? Can we host the file on github repo/wiki in some way?

@Ugtan
Copy link
Collaborator Author

Ugtan commented Aug 15, 2021

This will generate the api documentation on app/swagger and app/redoc endpoint. I don't think so there is any other way to generate it on wiki rather than writing it manually. @rtgdk

@@ -52,6 +68,8 @@
path('api-auth/', include(("rest_framework.urls", 'api_auth'), namespace='rest_framework')),
path('oauth/', include('social_django.urls', namespace='social')),
path('auth/', include(("rest_framework_social_oauth2.urls", 'github_auth'), namespace='github_social')),
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
Copy link
Collaborator

Choose a reason for hiding this comment

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

What is redoc/ for?

@rtgdk
Copy link
Collaborator

rtgdk commented Aug 29, 2021

@Ugtan ping

Copy link
Collaborator

@rtgdk rtgdk left a comment

Choose a reason for hiding this comment

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

We need to rethink about drf-yasg module whether it suits our apis. Or we need to change how we model the apis parameters and response and make it visible on the URLs side to make swagger pick up the documentation. This needs to be investigated. Not merging this PR as it doesn't add any value right now.

Let's continue to use the wiki endpoint - https://github.com/spdx/spdx-online-tools/wiki/REST-API-Fields-Request-and-Response for Rest API request and response parameter.

description="A sample API for learning DRF",
terms_of_service="https://www.google.com/policies/terms/",
contact=openapi.Contact(email="hello@example.com"),
license=openapi.License(name="BSD License"),
Copy link
Collaborator

Choose a reason for hiding this comment

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

Info needs to be changed.

@renderer_classes((JSONRenderer,))
def validate(request):
""" Handle Validate api request """
if request.method == 'GET':
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why did we remove all GET endpoints?

public=True,
permission_classes=(permissions.AllowAny,),
)

Copy link
Collaborator

Choose a reason for hiding this comment

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

The redoc/ and swagger/ endpoints are not showing any parameters and response for drf apis,
Screenshot 2022-03-13 at 7 02 26 PM

The values are coming up empty. How will drf-yasg pick up parameters information from the serializer defined in views.py file?

@@ -74,6 +74,8 @@
'social_django',
'oauth2_provider',
'rest_framework_social_oauth2',
'corsheaders',
Copy link
Collaborator

Choose a reason for hiding this comment

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

why do we need corsheader?

@rtgdk rtgdk mentioned this pull request Mar 13, 2022
@rtgdk
Copy link
Collaborator

rtgdk commented Mar 13, 2022

@goneall @Ugtan Not merging this to python3 as it doesn't provide any value right now. The swagger spec generated are empty. Maybe we need to rethink where to provide the API request and response structure. drf-yasf doesn't seem to pick up parameters from views.py. Maybe I am missing something here. Open to suggestions on what to do next.

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.

2 participants