swaggerIniziare con lo spavalderia


Osservazioni

Questa sezione fornisce una panoramica di cosa sia lo swagger e perché uno sviluppatore potrebbe volerlo utilizzare.

Dovrebbe anche menzionare qualsiasi argomento di grandi dimensioni all'interno di spavalderia e collegarsi agli argomenti correlati. Poiché la Documentation for swagger è nuova, potrebbe essere necessario creare versioni iniziali di tali argomenti correlati.

Introduzione - Installazione - Configurazione (sviluppo in Node.js)

Introduzione:

Swagger è un insieme di regole / specifiche per un formato che descrive le API REST. Fornisce un potente e attivamente sviluppato ecosistema di strumenti attorno a questa specifica formale come generatori di codice ed editori. La parte migliore di Swagger è che la documentazione di metodi, parametri e modelli è strettamente integrata nel codice del server, consentendo alle API di rimanere sempre sincronizzate. Ecco un link che fornisce una breve panoramica di ciò che è spavalderia: iniziare.

Specifiche di scrittura:

Le specifiche possono essere scritte in JSON o YAML. E così facciamo il file swagger.json o swagger.yaml di conseguenza. L'editor online può essere utilizzato per creare il file. Ecco un link che descrive la sintassi per le specifiche: http://swagger.io/specification/

Modi per usare lo spavalderia:

  1. Approccio API-first (approccio Top-down): Usa editor swagger → Scrivi definizioni swagger → Usa swagger-codegen e swagger-ui per generare API
  2. Primo approccio al servizio (approccio bottom-up): sviluppo classi di risorse JAX-RS usando annotazioni swagger → Usa swagger-core per generare automaticamente le definizioni swagger → Usando swagger-codegen e swagger-ui per generare API e documentazioni client. Quanto sopra può essere fatto durante la generazione di Maven durante il plug-in swavger maven.

Installazione e configurazione

In questa sezione installeremo swagger, configureremo l'interfaccia utente swagger e genereremo il lato server e l'SDK client che lo utilizza. Per installare swagger usando Node package manager eseguire il seguente comando:

npm install -g swagger

L'uso del flag '-g' assicurerà che il modulo sia installato a livello globale. Successivamente, creeremo un progetto usando il seguente comando:

swagger project create <project-name>

Questo richiederà all'utente di selezionare un framework per lo sviluppo delle API REST. Express può essere selezionato per lo stesso. Questo creerà la directory del progetto con i seguenti elementi e un file README.md in ciascuno di essi:

  • API /
    • controllori /
    • aiutanti /
    • schernisce /
    • spavalderia /
  • config /
  • test/
    • API /
      • controllori /
      • aiutanti
  • app.js
  • package.json

Il server è fondamentalmente pronto ora e può essere avviato utilizzando questo comando per essere eseguito nella radice del progetto:

swagger project start

Se il server host è impostato come localhost e il numero di porta non viene modificato nel file app.js , il server viene avviato all'indirizzo: http://localhost:10010 Ora l'interfaccia utente swagger può essere utilizzata per sviluppare ulteriormente le nostre API REST. Questo può essere avviato in un nuovo terminale usando:

swagger project edit

Questo aprirà l'editor swagger in una scheda del browser su una porta generata casualmente. Un esempio di esempio La richiesta GET può essere vista già presente nel file swagger.yaml. Qualsiasi ulteriore modifica a questo file causerà il riavvio del server autonomamente.

Nella sezione dei percorsi, il valore utilizzato per x-swagger-router-controller dovrebbe essere il nome del file javascript nella cartella dei controller. Come esempio, hello_world.js dovrebbe essere presente nella directory dei controller. Inoltre, il valore per parametro operationId rappresenta il nome della funzione nel file javascript sopra. È qui che deve essere scritta la logica aziendale. Pertanto, la nostra configurazione swagger è completa e può essere utilizzata per sviluppare ulteriormente la nostra API.