0
394
VistasCómo describir parámetros en DRF Docs
Estoy usando Django REST Framework v3.6 documentación interactiva django_rest_framework.documentation ( no django-rest-swagger ).
Básicamente, estoy siguiendo la documentación oficial y uso esto en mi configuración de URLset:
from rest_framework.documentation import include_docs_urls urlpatterns = [ url(r"^", include_docs_urls(title="My API")), ... ] Todo parece funcionar y obtengo una buena página de documentación interactiva, pero tengo un ViewSet con lookup_field = "slug" y una cosa sobre la documentación generada me molesta:
Quiero tener información útil en esa descripción, como "una identificación alfanumérica única asignada permanentemente" o algo entre esas líneas, pero no puedo encontrar ninguna documentación de donde provienen estos datos.
Hay una solución, pero realmente no quiero definir todo el esquema explícitamente . Quiero declarar mis clases con buenas cadenas de documentos y hacer que los documentos se generen automáticamente. También encontré una sugerencia para poner slug -- here goes the description en la cadena de documentación, pero no parece funcionar: el texto solo aparece con el resto de la descripción con formato de Markdown.
Entonces... me pregunto sobre dos cosas:
- (Una pregunta específica) ¿Dónde completo esta descripción del parámetro de ruta?
- (Versión más genérica de la misma pregunta) ¿Cuál es la mejor manera de aprender cómo los esquemas se generan automáticamente a partir del código?
2 Respuestas
Responde la pregunta0
Ah, lo encontré. Respondiendo a mi propia pregunta.
La documentación de DRF no es detallada sobre este asunto (o me perdí la parte donde está), pero menciona la clase rest_framework.schemas.SchemaGenerator y parece que esta clase realmente hace todo el trabajo de introspección. Afortunadamente, el código fuente está bien estructurado y es fácil de leer.
Esos campos de ruta son generados por el método get_path_fields (lo encontré rastreando la ruta de ejecución: get_schema → get_links → get_link ), y encontré que las descripciones provienen del atributo help_text de los campos del modelo .
Así que en mi modelo he especificado:
class MyResource(models.Model): slug = models.CharField(unique=True, help_text=_("unique alphanumeric identifier")) ...¡Y funcionó!
0
Una cosa importante aún no estaba cubierta. Es cierto que una descripción proviene del atributo help_text , pero esto no es suficiente. Descubrí que el generador de esquemas se basa en el atributo de conjunto de queryset de la vista para determinar un modelo. Por lo tanto, tenga en cuenta que necesita definirlo incluso si no lo necesita. Por ejemplo en caso de usar APIView .