Esquema de OpenAPI 3.0 con Swagger UI para la aplicación Django RESTful

Usemos drf-spectacular para simplificar la creación de hermosos documentos para su aplicación Django de acuerdo con la especificación OpenAPI versión 3. ¿Suena fácil? no era para mi... Dado que todavía soy un programador relativamente novato, lucho constantemente con diferentes temas y casi siempre buscar ayuda en Google. Pero no en este caso. Decidí agregar el marco Django REST a mi cadena de herramientas y combinarlo con tecnologías como OAS 3.0. Vi lo genial que se vería la documentación de la API cuando descubrí FastAPI por primera vez y quise implementar la interfaz de usuario de Swagger en mi propia aplicación. La opción más popular, en mi opinión, fue drf-yasg, pero dice explícitamente que "es poco probable que drf-yasg obtenga soporte para OpenAPI 3.0 pronto, o nunca". Bueno, la segunda mejor opción en esta dirección es drf-espectacular, pero no pude averiguar cómo documentar mi API simplemente siguiendo los ejemplos proporcionados (por cierto, lo hice por primera vez). La solución que se me ocurrió es crear documentación con herramientas DRF estándar (la forma más fácil), luego generar esquemas OpenAPI 2 con drf-yasg (ya que tiene una descripción más completa del proceso) y finalmente ajustar la configuración para usar . drf-espectacular Aquí voy a acortar esta ruta para usted usando el ejemplo de de la documentación de DRF y agregando algo de personalización para implementar la interfaz de usuario de Swagger con la versión 3 de la especificación. Así que, sin más preámbulos, ¡sé valiente y sígueme! inicio rápido Marco REST de Django Comenzamos con un par de pasos que son ligeramente diferentes de la documentación oficial de DRF. Omitiré algunos detalles específicos del marco en sí y si siente que le falta información para su propia implementación, simplemente explore el sitio oficial o haga una pregunta en la sección de comentarios a continuación. 1. Configuración del proyecto Lo primero es lo primero, cree el directorio del proyecto e ingréselo. mkdir tutorial tutorial cd Luego verifique si pipenv está instalado para crear un entorno virtual y aislar las dependencias de su paquete. pip3 install pipenv Instale Django y Django REST framework en el entorno virtual. pipenv install django pipenv install djangorestframework Activar entorno virtual. pipenv shell Ahora, después de un poco de preparación, es hora de configurar un nuevo proyecto con una sola aplicación. Tenga en cuenta el final "." carácter - no es un error tipográfico. django-admin startproject config . django-admin startapp quickstart Como verificación intermedia, comparemos el diseño de nuestro proyecto, que en este punto debería verse así. Ahora sincronice la base de datos por primera vez, lo que agregará un nuevo archivo SQLite al diseño mencionado anteriormente. python manage.py migrate Después de una migración exitosa, cree un de usuario inicial con contraseña . Se le pedirá que ingrese la contraseña a ciegas. administrador password123 python manage.py createsuperuser --email admin@example.com --username admin 2. Serializadores ¡Arremangarse porque estamos empezando a codificar más! Dentro de su directorio de tutoriales, ejecute el siguiente comando para crear un nuevo expediente. serializers.py touch quickstart/serializers.py Abra este archivo recién creado con su IDE favorito y llénelo con el siguiente contenido. django.contrib.auth.models User, Group rest_framework serializers model = User fields = [ , , , ] model = Group fields = [ , ] from import from import : class UserSerializer (serializers.HyperlinkedModelSerializer) : class Meta 'url' 'username' 'email' 'groups' : class GroupSerializer (serializers.HyperlinkedModelSerializer) : class Meta 'url' 'name' 3. Vistas Después de eso, abre y comience a escribir o simplemente copie y pegue, como desee, sin juzgar 😉 quickstart/views.py django.contrib.auth.models User, Group rest_framework viewsets rest_framework permissions .serializers UserSerializer, GroupSerializer queryset = User.objects.all().order_by( ) serializer_class = UserSerializer permission_classes = [permissions.IsAuthenticated] queryset = Group.objects.all() serializer_class = GroupSerializer permission_classes = [permissions.IsAuthenticated] from import from import from import from import : class UserViewSet (viewsets.ModelViewSet) """ API endpoint that allows users to be viewed or edited. """ "-date_joined" : class GroupViewSet (viewsets.ModelViewSet) """ API endpoint that allows groups to be viewed or edited. """ En lugar de escribir varias vistas, todo el comportamiento común se agrupa en clases denominadas ViewSets. Para fines futuros, puede dividirlos fácilmente en vistas individuales si es necesario, pero el uso de conjuntos de vistas mantiene la lógica de vista bien organizada y muy concisa. 4. URL Es hora de que las URL de la API estén disponibles. Navegue a la carpeta de configuración y cambie contenido a lo siguiente. urls.py django.urls include, path rest_framework routers quickstart views router = routers.DefaultRouter() router.register( , views.UserViewSet) router.register( , views.GroupViewSet) urlpatterns = [ path( , include(router.urls)), path( , include( , namespace= )), ] from import from import from import r"users" r"groups" # Wire up our API using automatic URL routing. # Additionally, login URLs included for the browsable API. "" "api-auth/" "rest_framework.urls" "rest_framework" 5. Paginación La paginación le permite controlar cuántos objetos por página se devuelven. Para habilitarlo, agregue las siguientes líneas en la parte inferior de config/settings.py REST_FRAMEWORK = { : , : , } "DEFAULT_PAGINATION_CLASS" "rest_framework.pagination.PageNumberPagination" "PAGE_SIZE" 10 En realidad, no necesitamos esta configuración a menos que decidas llenar la base de datos con muchos datos más adelante. 6. Configuración dentro del mismo archivo, para fines de prueba, habilite todos los hosts agregando "*" a ALLOWED_HOSTS. settings.py ALLOWED_HOSTS = [ ] "*" También agregue "rest_framework" a INSTALLED_APPS. INSTALLED_APPS = [ ... , ] "rest_framework" 7. Prueba de la API Es hora de probar lo que hemos logrado hasta ahora. Iniciemos el servidor. python manage.py runserver Ahora en su navegador abra la URL . Probablemente esté viendo la página como esta, lo que significa que debe iniciar sesión (esquina superior derecha) con las credenciales de superusuario que creó al final del paso 1. http://127.0.0.1:8000/users/ Después de un inicio de sesión exitoso, la página debería verse así. Si es así, ¡buen trabajo! Hasta aquí todo bien y pasemos al siguiente paso: ¡cambiar esta interfaz de usuario bastante elegante a la increíble Swagger! drf-espectacular Primero, detenga el servidor presionando CONTROL-C. Después de esto, debe instalar drf-spectacular en su entorno virtual. pipenv install drf-spectacular Entonces, en agregue drf-espectacular a las aplicaciones instaladas. A estas alturas, el resultado debería ser así. settings.py INSTALLED_APPS = [ , , , , , , , , ] "django.contrib.admin" "django.contrib.auth" "django.contrib.contenttypes" "django.contrib.sessions" "django.contrib.messages" "django.contrib.staticfiles" "rest_framework" "drf_spectacular" Finalmente, registre AutoSchema con DRF agregando una línea adicional a la configuración REST_FRAMEWORK también dentro archivo para que el resultado se vea así. settings.py REST_FRAMEWORK = { : , : , : , } "DEFAULT_PAGINATION_CLASS" "rest_framework.pagination.PageNumberPagination" "PAGE_SIZE" 10 "DEFAULT_SCHEMA_CLASS" "drf_spectacular.openapi.AutoSchema" Al momento de escribir este texto, la versión más reciente de drf-spectacular es la 0.11.1. Por lo tanto, tenga en cuenta que puede haber algunos cambios importantes en el código, ya que todavía está por debajo de 1.xx y en desarrollo activo. OpenAPI 3.0 con interfaz de usuario de Swagger Y ahora la parte más complicada, que fue especialmente difícil para mí. Con suerte, evitarás la miseria por la que pasé y saltarás directamente a la parte feliz 🎊 1. URL Cambiar a la dentro de la carpeta de configuración y modifique el contenido de la siguiente manera. urls.py django.urls include, path rest_framework routers quickstart views drf_spectacular.views SpectacularAPIView, SpectacularSwaggerView router = routers.DefaultRouter() router.register( , views.UserViewSet) router.register( , views.GroupViewSet) urlpatterns = [ path( , include(router.urls)), path( , include( , namespace= )), path( , SpectacularAPIView.as_view(), name= ), path( , SpectacularSwaggerView.as_view( template_name= , url_name= ), name= , ), ] from import from import from import from import r"users" r"groups" # Wire up our API using automatic URL routing. # Additionally, login URLs included for the browsable API. "" "api-auth/" "rest_framework.urls" "rest_framework" # OpenAPI 3 documentation with Swagger UI "schema/" "schema" "docs/" "swagger-ui.html" "schema" "swagger-ui" Básicamente, acaba de agregar una nueva importación y se requieren dos rutas para la interfaz de usuario de Swagger. 2. Plantilla Ahora vamos a crear una carpeta para una plantilla de documentación API personalizada con un nuevo archivo dentro. Supongo que su terminal permanece en el mismo directorio raíz todo este tiempo: tutorial. mkdir templates touch templates/swagger-ui.html Entonces abre y pega el siguiente código. Solo una nota rápida: tuve dificultades incluso con este fragmento de código tomado de la , por lo que ha cambiado un poco, aunque puede parecer familiar. swagger-ui.html documentación de DRF Swagger html head title title meta charset "utf-8" meta name "viewport" content "width=device-width, initial-scale=1" link rel "stylesheet" type "text/css" href "https://unpkg.com/swagger-ui-dist@3/swagger-ui.css" head body div id "swagger-ui" div script src "https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js" script script ui = SwaggerUIBundle({ : , : , : [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ], : , : { request.headers[ ] = request; } }) const url "{% url 'schema' %}" dom_id '#swagger-ui' presets layout "BaseLayout" requestInterceptor ( ) => request 'X-CSRFToken' "{{ csrf_token }}" return script body html 3. Configuración Y de nuevo volver a dentro de la carpeta de configuración. Busque TEMPLATES y cambie la línea "DIRS" para que todo el bloque sea el siguiente para decirle a Django dónde buscar nuestra plantilla personalizada. settings.py TEMPLATES = [ { : , : [BASE_DIR / ], : , : { : [ , , , , ], }, }, ] "BACKEND" "django.template.backends.django.DjangoTemplates" "DIRS" "templates" "APP_DIRS" True "OPTIONS" "context_processors" "django.template.context_processors.debug" "django.template.context_processors.request" "django.contrib.auth.context_processors.auth" "django.contrib.messages.context_processors.messages" Verificación final del diseño del proyecto solo para asegurarnos de que estamos en la misma página. Después de todas esas configuraciones, activemos el servidor y abramos la URL http://127.0.0.1:8000/docs/ ¡He aquí! La documentación de la interfaz de usuario de Swagger implementada en el estándar OpenAPI 3.0 🎉 Las mejoras adicionales solo dependen de usted, pero hay un par de ideas: ampliar la gama de formatos de datos disponibles, por ejemplo, con o ; djangorestframework-xml djangorestframework-yaml use el decorador @extend_schema para agregar información adicional a sus vistas; anule la configuración predeterminada especificando en settings.py; SPECTACULAR_SETTINGS cree una página de marca aplicando su propio CSS a la plantilla de documentos;