Come dovrei usare Swagger con Hapi?

Question

Ho un'applicazione Hapi ordinaria che sto progettando di migrare a Swagger. Ho installato swagger-node utilizzando le istruzioni ufficiali e ho scelto Hapi durante l'esecuzione di "swagger project create". Tuttavia, ora sono confuso perché ci sembrano essere diverse biblioteche per l'integrazione di spavalderia-nodo e Hapi:

1. hapi-swagger: il più popolare
2. hapi-swaggered: un po 'popolare
3. swagger-hapi: impopolare e non che attivo ma usato dalla libreria ufficiale Swagger Node.js (cioè swagger-node) come predefinita per Hapi progetti

ho pensato spavalderia-Hapi è stato l'approccio "ufficiale", fino a quando ho cercato di trovare le informazioni su come fare varie configurazioni su percorsi Hapi (ad es. autorizzazione, scoping, ecc.). Sembra anche che gli approcci siano fondamentalmente diversi, swagger-hapi prendendo la definizione di Swagger come input e generando automaticamente le rotte, mentre hapi-swagger e hapi-swagger sembrano avere un approccio simile l'uno con l'altro generando solo la documentazione dell'API di Swagger dal semplice vecchio Hapi definizioni di percorso.

Considerando la quantità di contributori e il numero di download, l'hapi-swagger sembra essere la strada da percorrere, ma non sono sicuro su come procedere. Esiste un modo "ufficiale" di Swagger per configurare Hapi, e se esiste, come posso impostare l'autenticazione (preferibilmente usando hapi-auth-jwt2 o un'altra soluzione simile di JWT) e l'autorizzazione?

MODIFICA: Ho trovato anche swaggerize-hapi, che sembra essere gestito dal team kraken.js open source di PayPal, che indica che potrebbe avere una sorta di supporto aziendale (sempre una buona cosa). swaggerize-hapi sembra molto simile a hapi-swagger, anche se quest'ultimo sembra fornire più funzionalità out-of-the-box (principalmente Editor Swagger).

Answer 1

Modifica: Punto 3. Dalla tua domanda e capire cosa fa realmente lo swagger-hapi è molto importante. Non serve direttamente swagger-ui html. Non è destinato a, ma sta abilitando l'intera idea di spavalderia (che gli altri progetti nei punti 1 e 2 sono in realtà un po 'invertiti). Vedi sotto.

Si scopre che quando si utilizza swagger-node e swagger-hapi non è necessario tutto il resto dei pacchetti che hai citato, fatta eccezione per l'utilizzo di swagger-ui direttamente (che viene utilizzato da tutti gli altri in ogni modo - sono avvolgendolo in loro dipendenze)

Voglio condividere la mia comprensione fino ad ora in questo puzzle hapi/swagger, spero che queste 8 ore che ho trascorso possano aiutare anche gli altri.

librerie come hapi-swaggered, hapi-swaggered-ui, anche hapi-swagger - Tutti seguono lo stesso approccio - che potrebbe essere descritto così:

You document your API while you are defining your routes

sono un po 'seduti a parte l'idea principale del swagger-node ed il boilerplate hello_world progetto creato con swagger-cli, che hai citato che usi.

Mentre swagger-node e swagger-hapi (NOTA che la sua diversa da hapi-swagger) dicono:

You define all your API documentation and routes **in a single centralized place - swagger.yaml**

e poi basta solo concentrarsi sulla scrittura Logic Controller. Il progetto boilerplate fornito con swagger-cli sta già esponendo questo posto centralizzato swagger.yaml come json attraverso l'endpoint swagger.

Ora, perché il progetto swagger-ui cui tutti i pacchetti di cui sopra stanno facendo uso di per mostrare l'interfaccia utente, è solo un mucchio di html statico - al fine di utilizzarlo, si hanno due opzioni:

• 1) per ospitare questo html statico dall'app

• 2) per ospitarlo su un'app Web separata o caricare anche index.html direttamente dal file system.

In entrambi i casi non vi resta che alimentare la spavalderia-ui con il JSON spavalderia - che, come detto in precedenza è già esposti dal /swagger endpoint.

L'unica avvertenza se si sceglie l'opzione 2) è che è necessario abilitare cors per quel punto finale che è risultato essere molto facile. Basta cambiare il tuo default.yaml, per usare anche la cornamusa. Si prega di vedere questo thread per come farlo.

Come detto in precedenza da @Kitanotori, anche io non vedo il punto di documentare il codice a livello di codice. L'idea di descrivere semplicemente tutto in un unico posto e di creare sia il codice che il motore di documentazione per capirlo, è grandiosa.