Esiste un modo per generare automaticamente la documentazione Swagger (o simile) per un servizio di Nancy?Esiste un modo automatico per documentare i servizi di Nancy?
Ho trovato Nancy.Swagger, ma non ci sono informazioni su come utilizzarlo e l'applicazione demo non sembra dimostrare documentazione generativa (se lo fa, non è ovvio).
Qualsiasi aiuto sarebbe apprezzato. Grazie!
sto citando la risposta dell'autore qui dal https://github.com/khellang/Nancy.Swagger/issues/59
L'installazione dovrebbe essere molto semplice, basta tirare verso il basso il pacchetto NuGet, aggiungere moduli di metadati per descrivere i percorsi, e API-docs colpito /. Questo dovrebbe portarti il JSON. Se vuoi aggiungere anche swagger-ui, devi aggiungerlo manualmente in questo momento.
C'è un bel articolo qui: http://www.c-sharpcorner.com/article/generating-api-document-in-nancy-using-swagger/
Sembra che si devono ancora aggiungere spavalderia-ui separatamente.
Nel mio progetto attuale ho cercato molto in questo problema. Ho usato sia nancy.swagger che nancy.swagger.attributes.
Ho rapidamente scartato Nancy.swagger, perché per me personalmente non sembra corretto dover creare una classe di documentazione pura per ogni modulo nancy. La soluzione degli attributi era un po '"più pulita" - almeno la base di codice e la documentazione erano in un unico posto. Ma molto velocemente questo è diventato irrinunciabile. Il codice del modulo è illeggibile a causa di molti attributi. Nulla viene generato automaticamente: devi inserire il percorso, tutti i parametri, anche il metodo http come attributo. Questo è un enorme sforzo di duplicazione. I problemi arrivarono molto velocemente, alcuni esempi:
È troppo facile dimenticare di aggiornare gli attributi (per non parlare della soluzione del modulo di documentazione), che porta a discrepanze tra la documentazione e il codice effettivo. Il nostro team di interfaccia utente è in un altro paese e hanno avuto qualche problema nell'utilizzo delle API perché docu non era aggiornato.
La mia soluzione? Non mescolare codice e documentazione. Generare docu dal codice (come fa Swashbuckle) È ok, ma in realtà scrivere docu nel codice e provare a pubblicare il codice in docu NON è così. Non è meglio che scriverlo in un documento Word per i tuoi clienti.
Se vuoi Swagger docu, fallo come Swagger. - Passa un po 'di tempo con Swagger.Editor e crea davvero la tua API in YAML. Sembra tutto testo e difficile, ma una volta che ci si abitua, è no. - Passa un po 'di tempo con Swagger.Codegen e adattalo (fa già un buon lavoro per generare il codice del server di Nancy e con alcune modifiche ai modelli di baffi era proprio quello di cui avevo bisogno). - Automatizza il tuo processo: scrivi un paio di lotti per generare i tuoi moduli e modelli da yaml e copiali nel tuo repository.
Vantaggi?Un bel po ': -
Così ogni volta che cambia qualcosa nel contratto di REST, tutte le basi di codice sono rigenerato e aggiunto a progetti in un unico lotto. Devo solo dire ai team che qualcosa è stato aggiornato. Non devono guardare attraverso alcuni documenti e cercarli. Hanno solo il loro codice rigenerato e probabilmente vedono alcuni errori di compilazione, in caso di rotture delle modifiche.
Continuo a utilizzare nancy.swagger (.annotations)? Sì, lo uso in un altro progetto, che ha solo un endpoint con un paio di metodi. Non cambiano spesso. Non vale la pena di impostare tutto, ho il mio swagger docu attivo e funzionante. Ma se il tuo progetto è grande, l'API sta cambiando, e hai più basi di codice a seconda della tua API, il mio consiglio è di investire un po 'di tempo in una vera e propria configurazione di swagger.
"dovrebbe", sì. In realtà non funziona –