Swagger Documentation

Gwells and Swagger

| Official Swagger Docs | drf-yasg Docs | GWELLS Swagger Docs

Gwells automatically generates its Swagger documentation using drf-yasg -- Yet Another Swagger Generator. Included are some tips and tricks for working with this package.

How to not generate

By default, drf-yasg generates its documents for all existing endpoints, if you're trying to prevent an endpoint from being documented you can prevent the behaviour by adding "auto_swagger = None" to the class.

Comments

For generating the appropriate comments in your Swagger documents, there is two realms to go about this, consider the following two class examples

# Exmaple 1
class WellExportListAPIViewV2(ListAPIView):
    """Returns CSV or Excel data for wells."""
    permission_classes = (WellsEditOrReadOnly,)
    model = Well

# Example 2
class WellExportListAPIViewV2(ListAPIView):
    """
    Here is code documentation about the WellExportListAPIViewV2
    get: Returns CSV or Excel data for wells.
    post: Uploads a CSV or Excel data for wells
    
    patch:
    Updates a previously uploaded CSV or Excel file for a well
    """
    permission_classes = (WellsEditOrReadOnly,)
    model = Well

[Example: Document generation]

Pretend this class takes three HTTP Requests: GET, POST, and PATCH.

In Example 1, there is a non-specified line of documentation. The Swagger generator for all three supported HTTP methods will apply that single comment line to each request.

In Example 2, we have matched the request to the documentation with the METHOD: syntax. When the three methods generate their Swagger documentation, their comments will reflect the following comment. The initial documentation at the top of the class is ignored. As you can see in the example, you can group them as single line, or multi-line

It's worth noting that the generated docs do pick up on the line breaks, and so if you break a comment midway due to length, that will be reflected in the resulting documentation.

Overriding Query Params

Sometimes not all QueryParams will appear in the document, you can manually add them using the following syntax.

This just gets added to the class

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

class YourClass:

    @swagger_auto_schema(
        manual_parameters =[
            openapi.Parameter(
                name='longitude',
                in_=openapi.IN_QUERY,
                type=openapi.TYPE_NUMBER,
                description="Longitude Coordinate"
            ),
            openapi.Parameter(
                name='latitude',
                in_=openapi.IN_QUERY,
                type=openapi.TYPE_NUMBER,
                description="Latitude Coordinate"
            )
        ]
    )

[Swagger Auto Schema Override Example]

In this example manual parameters are defined against the OpenAPI Schema

Key	purpose	value
name	Name of the Query Parameter	latitude
in_	Parameter Location	openapi.IN_QUERY
type	Parameter Type	openapi.TYPE_NUMBER
description	Description of Parameter	Longitude Coordinate

[Put it all together]

There's Plenty more out there beyond these examples. Remember to checkout the Official Documentation