Skip to content

Commit 7fa5ee0

Browse files
committed
documentation corrections for openapi
1 parent 7dd12a1 commit 7fa5ee0

File tree

3 files changed

+25
-13
lines changed

3 files changed

+25
-13
lines changed

README.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,10 @@ installed and activated:
134134
$ django-admin loaddata drf_example --settings=example.settings
135135
$ django-admin runserver --settings=example.settings
136136

137-
Browse to http://localhost:8000
137+
Browse to
138+
* http://localhost:8000 for the list of available collections (in a non-JSONAPI format!),
139+
* http://localhost:8000/swagger-ui/ for a Swagger user interface to the dynamic schema view, or
140+
* http://localhost:8000/openapi for the schema view's OpenAPI specification document.
138141

139142

140143
Running Tests and linting

docs/getting-started.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,10 @@ From Source
8484
django-admin runserver --settings=example.settings
8585

8686

87-
Browse to http://localhost:8000
87+
Browse to
88+
* [http://localhost:8000](http://localhost:8000) for the list of available collections (in a non-JSONAPI format!),
89+
* [http://localhost:8000/swagger-ui/](http://localhost:8000/swagger-ui/) for a Swagger user interface to the dynamic schema view, or
90+
* [http://localhost:8000/openapi](http://localhost:8000/openapi) for the schema view's OpenAPI specification document.
8891

8992
## Running Tests
9093

docs/usage.md

+17-11
Original file line numberDiff line numberDiff line change
@@ -958,8 +958,6 @@ In order to produce an OAS schema that properly represents the JSON:API structur
958958
you have to either add a `schema` attribute to each view class or set the `REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS']`
959959
to DJA's version of AutoSchema.
960960

961-
You can also extend the OAS schema with additional static content (a feature not available in DRF at this time).
962-
963961
#### View-based
964962

965963
```python
@@ -979,16 +977,16 @@ REST_FRAMEWORK = {
979977
}
980978
```
981979

982-
### Adding static OAS schema content
980+
### Adding additional OAS schema content
983981

984-
You can optionally include an OAS schema document initialization by subclassing `SchemaGenerator`
985-
and setting `schema_init`.
982+
You can extend the OAS schema document by subclassing
983+
[`SchemaGenerator`](https://www.django-rest-framework.org/api-guide/schemas/#schemagenerator)
984+
and extending `get_schema`.
986985

987-
Here's an example that fills out OAS `info` and `servers` objects.
988986

989-
```python
990-
# views.py
987+
Here's an example that adds OAS `info` and `servers` objects.
991988

989+
```python
992990
from rest_framework_json_api.schemas.openapi import SchemaGenerator as JSONAPISchemaGenerator
993991

994992

@@ -1047,14 +1045,22 @@ is published.
10471045
### Generate a Dynamic Schema in a View
10481046

10491047
See [DRF documentation for a Dynamic Schema](https://www.django-rest-framework.org/api-guide/schemas/#generating-a-dynamic-schema-with-schemaview).
1050-
You will need to pass in your custom SchemaGenerator if you've created one.
10511048

10521049
```python
10531050
from rest_framework.schemas import get_schema_view
1054-
from views import MySchemaGenerator
10551051

10561052
urlpatterns = [
1057-
path('openapi', get_schema_view(generator_class=MySchemaGenerator), name='openapi-schema'),
1053+
...
1054+
path('openapi', get_schema_view(
1055+
title="Example API",
1056+
description="API for all things …",
1057+
version="1.0.0",
1058+
generator_class=MySchemaGenerator,
1059+
), name='openapi-schema'),
1060+
path('swagger-ui/', TemplateView.as_view(
1061+
template_name='swagger-ui.html',
1062+
extra_context={'schema_url': 'openapi-schema'}
1063+
), name='swagger-ui'),
10581064
...
10591065
]
10601066
```

0 commit comments

Comments
 (0)