Il django-rest-swagger non funziona bene con i modelerizer?

Question

Sto uscendo dalla documentazione sulla django-spavalderia github page, in particolare la parte chiamata "Come funziona". Mostra che puoi definire i tuoi parametri per la tua pausa API e visualizzare questi parametri nella tua pagina doc swagger.

L'esempio commentando è qualcosa di simile:

"""  
This text is the description for this API  
param1 -- A first parameter  
param2 -- A second parameter  
"""  

posso ottenere questo lavoro, ma il mio problema è come specificare se è richiesta la variabile, il suo tipo di parametro, e il suo tipo di dati. La pagina github mostra un example image di come potrebbe apparire il tuo swagger doc, e hanno le informazioni che ho appena menzionato. Ma quando commento i miei parametri personalizzati come mostra l'esempio, i miei parametri mostrano semplicemente come tipo di parametro: "query", tipo di dati: è vuoto e non mostra "required".

La cosa più vicina che ho trovato per una risposta era in this stackoverflow question. Sembra che un fornitore di risposte stia dicendo che django-rest-swagger genera la sua documentazione ispezionando automaticamente i serializzatori (che va bene), e che i modelerializer non conterranno abbastanza informazioni per django-rest-swagger per derivare correttamente i criteri che ho citato sopra. Capisco che non riesco a capire questo criterio, ma ci deve essere un modo per me di specificarlo manualmente allora.

Sono sicuro che il django-rest-swagger visualizzerebbe solo ciò che voglio se ho riscritto i miei modelerizer come solo serializzatori? Non c'è modo per me di dire manualmente a django-rest-swagger quale tipo di parametro e tipo di parametro di un parametro dovrebbe essere, e se è necessario?

So che mi manca qualcosa qui. Uso le visualizzazioni classiche e i modelerizer che sono quasi identici agli esempi nei tutorial di django-rest-framework. Sembra del tutto possibile che mi manchi solo una comprensione dei "tipi di parametri" in questo contesto. La mia API funziona alla grande e non voglio riscrivere i miei modelerizer su serializzatori solo per poter ottenere una migliore documentazione automatica tramite swagger.

Answer 1

Nella maggior parte dei casi ModelSerializer è ciò di cui hai bisogno, perché può essere personalizzato in base alle tue esigenze. Nella situazione ideale si dovrebbe definire tutti i vincoli, come richiesto attributo su un campo, nella classe del modello, ma ci sono momenti in cui non è architettonicamente possibile, allora si può ignorare un tale campo nella sottoclasse ModelSerializer:

from django.contrib.auth import get_user_model 
from rest_framework import serializers 


class UserSerializer(serializers.ModelSerializer): 
    first_name = serializers.CharField(required=True) 
    last_name = serializers.CharField(required=True) 

    class Meta: 
     model = get_user_model() 

nell'esempio precedente ho serializzare modello utente standard da Django e sovrascrivere richiesto attributi così, che first_name e cognome sono ora tenuti.

Naturalmente, ci sono casi in cui è difficile o impossibile utilizzare ModelSerializer allora si può sempre fallback a Serializer sottoclassi

Answer 2

Nel codice si ha:

"""
Questo testo è la descrizione per questa API
param1 - Un primo parametro
param2 - Un secondo parametro
"""

Try :

"" "Questo testo è la descrizione per questa API
param1 - Un primo parametro
param2 - Un secondo parametro
"""

ho trovato un po 'di Python e/o Django i plug-in richiedono la prima riga della docstring, che è quella con le prime tre virgolette di apertura per essere anche la riga che avvia la documentazione. Si potrebbe anche voler provare a non lasciare spazio tra l'ultima doppia quotazione e il T.

Answer 3

ModelSerializers sono il modo giusto per andare con DR-Swagger. Può essere un po 'difficile inseguire esattamente da dove vengono estratti i diversi campi di Swagger, ma spesso ho dovuto ricorrere al debugging passo-passo attraverso il processo di rendering della pagina per capire da dove venivano le cose.

A sua volta:

Obbligatorio? proviene dal parametro Field.required (impostato sul modello o sul campo Serializer). Descrizione deriva dal parametro Field.help_text.

Nella serializzazione DRF di nuovo stile, il testo della descrizione proviene dalla docstring di ViewSet. Se desideri documenti specifici del metodo, devi sovrascrivere la docstring per i singoli metodi, ad es. retrieve:

def retrieve(self, request, *args, **kwargs): 
    """Retrieve a FooBar""" 
    return super().retrieve(request, *args, **kwargs) 

Una cosa da notare è che DR-Swagger migrato a utilizzare la nuova logica dello schema DRF nella versione 2.0 (con DRF versione 3.5), che ha un paio di bordi grezzi ancora. Consiglio di attenermi alla versione 0.3.x di DR-Swagger, che (sebbene deprecata) ha più funzionalità e, secondo la mia esperienza, una serializzazione più affidabile.