Creare una documentazione delle rest api di DRF

[Karim]

Ciao lista, sto usando drf-yasg[1] per la generazione della documentazione swagger.

Purtroppo it's a pain in the arse da usare:

1) La documentazione e' scarna

2) Non capisco come modificare la generazione dei docs

3) Quel poco che ho modificato mi fa creare decorator che sono piu' grandi del codice dell'endpoint stesso.

Voi cosa usate per documentare le API? Io ho bisogno di poter fare esempi dell'uso dell'api e spiegare in dettaglio cosa fa e come deve essere usata

Ciao lista.

[1] https://github.com/axnsan12/drf-yasg

--

Karim N. Gorjux

[Riccardo Magliocchetti]

Ciao Karim,

Il 26/07/19 03:59, Karim ha scritto:

> Ciao lista, sto usando drf-yasg[1] per la generazione della documentazione
> swagger.
>
> Purtroppo it's a pain in the arse da usare:
>
> 1) La documentazione e' scarna
> 2) Non capisco come modificare la generazione dei docs
> 3) Quel poco che ho modificato mi fa creare decorator che sono piu' grandi
> del codice dell'endpoint stesso.

Hai visto che la 3.10 include la generazione dello schema OpenAPI?
https://www.django-rest-framework.org/community/3.10-announcement/


--
Riccardo Magliocchetti
@rmistaken

http://menodizero.it

[Paolo Melchiorre]

On Fri, Jul 26, 2019 at 9:18 AM Riccardo Magliocchetti
<riccardo.ma...@gmail.com> wrote:
> Il 26/07/19 03:59, Karim ha scritto:
> > Ciao lista, sto usando drf-yasg[1] per la generazione della documentazione
> > swagger.
> > Purtroppo it's a pain in the arse da usare:
> > 1) La documentazione e' scarna
> > 2) Non capisco come modificare la generazione dei docs
> > 3) Quel poco che ho modificato mi fa creare decorator che sono piu' grandi
> > del codice dell'endpoint stesso.
> Hai visto che la 3.10 include la generazione dello schema OpenAPI?
> https://www.django-rest-framework.org/community/3.10-announcement/

Sarebbe interessante sapere come gli altri usano questa funzionalità
per documentare le proprie API:
- generate lo schema in maniera statica e lo versionate
- fate generare lo schema dinamicamente
- come producete la documentazione html delle api
- come documentate le API

Insomma mi interessava sapere come altre persone e gruppi gestivano
questa parte in progetti reali.

Ciao,
Paolo

--
Paolo Melchiorre

https://www.paulox.net

[Riccardo Magliocchetti]

Il 26/07/19 10:14, Paolo Melchiorre ha scritto:

> On Fri, Jul 26, 2019 at 9:18 AM Riccardo Magliocchetti
> <riccardo.ma...@gmail.com> wrote:
>> Il 26/07/19 03:59, Karim ha scritto:
>>> Ciao lista, sto usando drf-yasg[1] per la generazione della documentazione
>>> swagger.
>>> Purtroppo it's a pain in the arse da usare:
>>> 1) La documentazione e' scarna
>>> 2) Non capisco come modificare la generazione dei docs
>>> 3) Quel poco che ho modificato mi fa creare decorator che sono piu' grandi
>>> del codice dell'endpoint stesso.
>> Hai visto che la 3.10 include la generazione dello schema OpenAPI?
>> https://www.django-rest-framework.org/community/3.10-announcement/
>
> Sarebbe interessante sapere come gli altri usano questa funzionalità
> per documentare le proprie API:
> - generate lo schema in maniera statica e lo versionate
> - fate generare lo schema dinamicamente
> - come producete la documentazione html delle api
> - come documentate le API

Io ho usato la generazione OpenAPI solo con progetti flask ma dovrebbe
applicarsi anche a quelli django:
- genero dinamicamente lo schema swagger
- mai generato la documentazione html staticamente, ma ho un endpoint con
l'interfaccia di swagger per leggere la documentazione ed avere il client per
testare le API
- documento le api documentando i metodi delle classi, uso un analogo di APIView

Aggiungo che tutto questo è esposto solo in sviluppo e non è pubblico. Lo schema
viene usato come contratto verso altri servizi interni che consumano quella API.