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                              <!DOCTYPE html> <   > 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;

Read My Stories

Este audio es producido en el idioma original de la historia!

Demasiado Largo; Para Leer

Make resilience your competitive advantage

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

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

Telegram: el puente de Crypto Island hacia el continente

Aumente su productividad con estas 18 herramientas para desarrolladores 🚀🔥

Las capas invisibles: por qué las entrevistas con los usuarios son un activo irremplazable

Una guía del arquitecto para crear una arquitectura de referencia para un lago de datos de IA/ML

Telegram: el puente de Crypto Island hacia el continente

Aumente su productividad con estas 18 herramientas para desarrolladores 🚀🔥

Las capas invisibles: por qué las entrevistas con los usuarios son un activo irremplazable

Una guía del arquitecto para crear una arquitectura de referencia para un lago de datos de IA/ML

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps