swaggerAan de slag met swagger


Opmerkingen

Deze sectie geeft een overzicht van wat swagger is en waarom een ontwikkelaar het misschien wil gebruiken.

Het moet ook alle grote onderwerpen binnen swagger vermelden en een link naar de gerelateerde onderwerpen bevatten. Aangezien de documentatie voor swagger nieuw is, moet u mogelijk eerste versies van die gerelateerde onderwerpen maken.

Introductie - Installatie - Setup (ontwikkelen in Node.js)

Invoering:

Swagger is een set regels / specificaties voor een indeling die REST API's beschrijft. Het biedt een krachtig en actief ontwikkeld ecosysteem van tools rond deze formele specificatie, zoals codegeneratoren en editors. Het beste deel van Swagger is dat de documentatie van methoden, parameters en modellen nauw zijn geïntegreerd in de servercode, waardoor API's altijd synchroon blijven. Hier is een link die een kort overzicht geeft van wat swagger is: aan de slag.

Schrijven specificaties:

De specificaties kunnen worden geschreven in JSON of YAML. En dus maken we het bestand swagger.json of swagger.yaml dienovereenkomstig. De online editor kan worden gebruikt voor het maken van het bestand. Hier is een link die de syntaxis voor specificaties beschrijft: http://swagger.io/specification/

Manieren om swagger te gebruiken:

  1. API-first-benadering (Top -downbenadering ): gebruik swagger-editor → schrijf swagger-definities → gebruik swagger-codegen en swagger-ui om API's te genereren
  2. Service first-benadering (bottom-up benadering): ontwikkel JAX-RS-resourceklassen met behulp van swagger-annotaties → Gebruik swagger-core om automatisch de swagger-definities te genereren → swagger-codegen en swagger-ui gebruiken om client-API's en documentatie te genereren. Het bovenstaande kan worden gedaan tijdens het bouwen van maven tijdens de plug-in voor swagger maven.

Installatie en instellingen

In deze sectie zullen we swagger installeren, de swagger UI instellen en de server-side en client SDK genereren met behulp van deze. Voer de volgende opdracht uit om swagger te installeren met Node package manager:

npm install -g swagger

Gebruik van de vlag '-g' zorgt ervoor dat de module wereldwijd wordt geïnstalleerd. Vervolgens maken we een project met de volgende opdracht:

swagger project create <project-name>

Dit vraagt de gebruiker om een raamwerk te selecteren voor het ontwikkelen van de REST API's. Express kan hiervoor worden geselecteerd. Hiermee maakt u de projectmap met de volgende items en een README.md-bestand in elk van deze:

  • api /
    • controllers /
    • helpers /
    • bespot /
    • branie/
  • config /
  • test/
    • api /
      • controllers /
      • helpers
  • app.js
  • package.json

De server is nu in principe gereed en kan worden gestart met deze opdracht om in project root te worden uitgevoerd:

swagger project start

Als de hostserver is ingesteld als localhost en het poortnummer niet is gewijzigd in het bestand app.js , wordt de server gestart op: http://localhost:10010 Nu kan de swagger UI worden gebruikt om onze REST API's verder te ontwikkelen. Dit kan in een nieuwe terminal worden gestart met:

swagger project edit

Dit opent de swagger-editor in een browsertabblad op een willekeurig gegenereerde poort. Een voorbeeld van een Hallo GET-verzoek is al aanwezig in het bestand swagger.yaml. Als u dit bestand verder wijzigt, wordt de server automatisch opnieuw opgestart.

In de padensectie moet de waarde die wordt gebruikt voor x-swagger-router-controller de javascript-bestandsnaam in de map controllers zijn. Als voorbeeld moet hello_world.js aanwezig zijn in de map met controllers. De waarde voor de parameter operationId vertegenwoordigt ook de functienaam in het bovenstaande javascript-bestand. Dit is waar bedrijfslogica moet worden geschreven. Onze installatie van de swagger is dus voltooid en kan worden gebruikt om onze API verder te ontwikkelen.