Verified Commit ed5d259c authored by David Haynes's avatar David Haynes 🙆
Browse files

v2 documentation for ViewSets

- now with markdown
- crispy forms used for better modals
- coreapi added per docs
parent 1e9404aa
...@@ -10,3 +10,6 @@ django-taggit-serializer==0.1.5 ...@@ -10,3 +10,6 @@ django-taggit-serializer==0.1.5
six==1.10.0 six==1.10.0
djangorestframework-gis==0.11.2 djangorestframework-gis==0.11.2
django-filter==1.0.4 django-filter==1.0.4
django-crispy-forms==1.6.1
markdown==2.6.8
coreapi==2.3.1
...@@ -2,6 +2,9 @@ ...@@ -2,6 +2,9 @@
api/views.py api/views.py
Rest Framework Class Views Rest Framework Class Views
Each ViewSet determines what data is returned when an API endpoint is hit. In
addition, we define filtering and documentation for each of these endpoints.
""" """
# Future Imports # Future Imports
from __future__ import (absolute_import, division, print_function, from __future__ import (absolute_import, division, print_function,
...@@ -25,29 +28,61 @@ class AlertViewSet(viewsets.ReadOnlyModelViewSet): ...@@ -25,29 +28,61 @@ class AlertViewSet(viewsets.ReadOnlyModelViewSet):
Some type of notification that is displayed to clients that conveys a message. Some type of notification that is displayed to clients that conveys a message.
Past examples include: Past examples include:
- random closings
- modified schedules being in effect - Random closings
- election reminder - Modified schedules being in effect
- advertising for other SRCT projects - Election reminder
- Advertising for other SRCT projects
Alerts last for a period of time until the information is no longer dank. Alerts last for a period of time until the information is no longer dank.
GET /api/alerts/ ---
## Default behavior
[GET /api/alerts/](/api/alerts/?format=json)
Return all Alert objects. Return all Alert objects.
Built-in query parameters: ## Built-in query parameters
### **Search**
[GET /api/alerts/?search=](/api/alerts/?search=&format=json)
GET /api/alerts/?search=
Query parameter that returns objects that match a keyword provided in the search. Query parameter that returns objects that match a keyword provided in the search.
GET /api/alerts/?ordering= **Example Usage**
[GET /api/alerts/?search=srct](/api/alerts/?search=srct&format=json)
Return any Alert objects that have the string "srct" located in one of its fields.
### **Ordering**
[GET /api/alerts/?ordering=](/api/alerts/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by. Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like: **Example Usage**
[GET /api/alerts/?ordering=urgency_tag](/api/alerts/?ordering=urgency_tag&format=json)
ie. Return all Alert objects ordered by urgency_tag ascending.
GET /api/alerts/?urgency_tag=major
will return the Alert objects that are tagged as "major" urgency. [GET /api/alerts/?ordering=-urgency_tag](/api/alerts/?ordering=-urgency_tag&format=json)
Return all Alert objects ordered by urgency_tag descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/alerts/?urgency_tag=major](/api/alerts/?urgency_tag=major&format=json)
Return all Alert objects that are tagged as "major" urgency.
""" """
# All model fields that are available for filtering # All model fields that are available for filtering
FILTER_FIELDS = ( FILTER_FIELDS = (
...@@ -79,27 +114,59 @@ class CategoryViewSet(viewsets.ReadOnlyModelViewSet): ...@@ -79,27 +114,59 @@ class CategoryViewSet(viewsets.ReadOnlyModelViewSet):
""" """
A Category is a grouping of Facilities that serve a common/similar purpose. A Category is a grouping of Facilities that serve a common/similar purpose.
ex. Examples:
- Dining
- Gyms - Dining
- Study areas (Libraries, The Ridge, JC, etc) - Gyms
- Study areas (Libraries, The Ridge, JC, etc)
---
## Default behavior
[GET /api/categories/](/api/categories/)
GET /api/categories/
Return all Category objects. Return all Category objects.
Built-in query parameters: ## Built-in query parameters
### **Search**
[GET /api/categories/?search=](/api/categories/?search=&format=json)
GET /api/categories/?search=
Query parameter that returns objects that match a keyword provided in the search. Query parameter that returns objects that match a keyword provided in the search.
GET /api/categories/?ordering= **Example Usage**
[GET /api/categories/?search=din](/api/categories/?search=din&format=json)
Return all Category objects that have a field that matches the string "din".
### **Ordering**
[GET /api/categories/?ordering=](/api/categories/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by. Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like: **Example Usage**
[GET /api/categories/?ordering=name](/api/categories/?ordering=name&format=json)
Return all Category objects filtered by name ascending.
[GET /api/categories/?ordering=-name](/api/categories/?ordering=-name&format=json)
Return all Category objects filtered by name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
ie. [GET /api/categories/?name=dining](/api/categories/?name=dining&format=json)
GET /api/categories/?name=dining
will return the Category object that is named "dining". Return the Category object that is named "dining".
""" """
# All model fields that are available for filtering # All model fields that are available for filtering
FILTER_FIELDS = ( FILTER_FIELDS = (
...@@ -128,22 +195,53 @@ class LocationViewSet(viewsets.ReadOnlyModelViewSet): ...@@ -128,22 +195,53 @@ class LocationViewSet(viewsets.ReadOnlyModelViewSet):
""" """
Represents a specific location that a Facility can be found. Represents a specific location that a Facility can be found.
GET /api/locations/ ---
## Default behavior
[GET /api/locations/](/api/locations/?format=json)
Return all Location objects. Return all Location objects.
Built-in query parameters: ## Built-in query parameters
### **Search**
[GET /api/locations/?search=](/api/locations/?search=&format=json)
GET /api/locations/?search=
Query parameter that returns objects that match a keyword provided in the search. Query parameter that returns objects that match a keyword provided in the search.
GET /api/locations/?ordering= **Example Usage**
Query parameter that orders the returned objects based on the provided field to order by.
[GET /api/locations/?search=johnson](/api/locations/?search=johnson&format=json)
Return all Location objects that have a field that matches the "johnson" string.
### **Ordering**
Order the returned objects based on the provided field.
[GET /api/locations/?ordering=](/api/locations/?ordering=&format=json)
Additionally, you can query against any field you like: **Example Usage**
ie. [GET /api/locations/?ordering=building](/api/locations/?ordering=building&format=json)
GET /api/locations/?building=Johnson+Center
will return all Location objects located in the "Johnson Center" building. Return all Location objects ordered by building name ascending.
[GET /api/locations/?ordering=-building](/api/locations/?ordering=-building&format=json)
Return all Location objects ordered by building name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/locations/?building=Johnson+Center](/api/locations/?building=Johnson+Center&format=json)
Return all Location objects located in the "Johnson Center" building.
""" """
# All model fields that are available for filtering # All model fields that are available for filtering
FILTER_FIELDS = ( FILTER_FIELDS = (
...@@ -174,30 +272,67 @@ class FacilityViewSet(viewsets.ReadOnlyModelViewSet): ...@@ -174,30 +272,67 @@ class FacilityViewSet(viewsets.ReadOnlyModelViewSet):
""" """
A Facility is some type of establishment that has a schedule of open hours and a location that serves a specific purpose that can be categorized. A Facility is some type of establishment that has a schedule of open hours and a location that serves a specific purpose that can be categorized.
GET /api/facilities/ ---
Return all Facility objects. We additionally filter out stale special_schedules to reduce client side calculations.
## Default behavior
[GET /api/facilities/](/api/facilities/?format=json)
Return all Facility objects. Additionally, we filter out stale special_schedules to reduce client side calculations.
## Built-in query parameters
### **Search**
Built-in query parameters: [GET /api/facilities/?search=](/api/facilities/?search=&format=json)
GET /api/facilities/?search=
Query parameter that returns objects that match a keyword provided in the search. Query parameter that returns objects that match a keyword provided in the search.
GET /api/facilities/?ordering= **Example Usage**
[GET /api/facilities/?search=south](/api/facilities/?search=south&format=json)
Return all Facility objects that have a field that matches the string "south".
### **Ordering**
[GET /api/facilities/?ordering=](/api/facilities/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by. Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like: **Example Usage**
[GET /api/facilities/?ordering=facility_name](/api/facilities/?ordering=facility_name&format=json)
Return all Facility objects ordered by facility_name ascending.
[GET /api/facilities/?ordering=-facility_name](/api/facilities/?ordering=-facility_name&format=json)
Return all Facility objects ordered by facility_name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
ie. [GET /api/facilities/?facility_name=Southside](/api/facilities/?facility_name=Southside&format=json)
GET /api/facilities/?facility_name=Southside
will return the Facility object that has "Southside" as its name.
Custom query parameters: Return the Facility object that has "Southside" as its name.
GET /api/facilities/?open_now ## Custom query parameters
Query parameter that only returns open Facility objects.
GET /api/facilities/?closed_now ### **open_now**
Query parameter that only returns closed Facility objects.
[GET /api/facilities/?open_now](/api/facilities/?open_now&format=json)
Only return open Facility objects.
### **closed_now**
[GET /api/facilities/?closed_now](/api/facilities/?closed_now&format=json)
Only return closed Facility objects.
""" """
# All model fields that are available for filtering # All model fields that are available for filtering
FILTER_FIELDS = ( FILTER_FIELDS = (
...@@ -265,22 +400,56 @@ class ScheduleViewSet(viewsets.ModelViewSet): ...@@ -265,22 +400,56 @@ class ScheduleViewSet(viewsets.ModelViewSet):
""" """
A period of time between two dates that represents the beginning and end of a "schedule" or rather, a collection of open times for a facility. A period of time between two dates that represents the beginning and end of a "schedule" or rather, a collection of open times for a facility.
GET /api/schedules/ ---
## Default behavior
[GET /api/schedules/](/api/schedules/?format=json)
Return all Schedule objects that have not expired. (ie. end_date is before today) Return all Schedule objects that have not expired. (ie. end_date is before today)
Built-in query parameters: ## Built-in query parameters
### **Search**
[GET /api/schedules/?search=](/api/schedules/?search=&format=json)
GET /api/schedules/?search=
Query parameter that returns objects that match a keyword provided in the search. Query parameter that returns objects that match a keyword provided in the search.
GET /api/schedules/?ordering= **Example Usage**
[GET /api/schedules/?search=south](/api/schedules/?search=south&format=json)
Return all Schedule objects that have a field matching the string "south".
### **Ordering**
[GET /api/schedules/?ordering=](/api/schedules/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by. Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like: **Example Usage**
[GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
Return all Schedule objects ordered by name ascending.
[GET /api/schedules/?ordering=-name](/api/schedules/?ordering=-name&format=json)
[GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
Return all Schedule objects ordered by name ascending.
Return all Schedule objects ordered by name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/schedules/?name=southside_main](/api/schedules/?name=southside_main&format=json)
ie. Return the Schedule object that has "southside_main" as its name.
GET /api/schedules/?name=southside_main
will return the Schedule object that has "southside_main" as its name.
""" """
# All model fields that are available for filtering # All model fields that are available for filtering
FILTER_FIELDS = ( FILTER_FIELDS = (
......
...@@ -245,6 +245,7 @@ INSTALLED_APPS = ( ...@@ -245,6 +245,7 @@ INSTALLED_APPS = (
'rest_framework', 'rest_framework',
'rest_framework_gis', 'rest_framework_gis',
'django_filters', 'django_filters',
'crispy_forms',
) )
""" """
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment