swaggerKomma igång med swagger


Anmärkningar

Det här avsnittet ger en översikt över vad swagger är, och varför en utvecklare kanske vill använda den.

Det bör också nämna alla stora ämnen inom swagger och länka till relaterade ämnen. Eftersom dokumentationen för swagger är ny kan du behöva skapa initialversioner av relaterade ämnen.

Introduktion - Installation - Installation (Utveckling i Node.js)

Introduktion:

Swagger är en uppsättning regler / specifikationer för ett format som beskriver REST-API: er. Det ger ett kraftfullt och aktivt utvecklat ekosystem av verktyg kring denna formella specifikation som kodgeneratorer och redaktörer. Det bästa med Swagger är att dokumentationen av metoder, parametrar och modeller är tätt integrerad i serverkoden, vilket gör att API: er alltid kan synkroniseras. Här är en länk som ger en kort överblick över vad som är swagger: att komma igång.

Skrivspecifikationer:

Specifikationerna kan skrivas i antingen JSON eller YAML. Och så gör vi filen swagger.json eller swagger.yaml i enlighet därmed. Online-redigeraren kan användas för att skapa filen. Här är en länk som beskriver syntaxen för specifikationer: http://swagger.io/specification/

Sätt att använda swagger:

  1. API-första metod (Top down-metod): Använd swagger-redigerare → Skriv swagger-definitioner → Använd swagger-codegen och swagger-ui för att generera API: er
  2. Service första metod (bottom up-metod): Utveckla JAX-RS resursklasser med hjälp av swagger-kommentarer → Använd swagger-core för att automatiskt generera swagger-definitionerna → Använd swagger-codegen och swagger-ui för att generera klient-API: er och dokumentationer. Ovanstående kan göras under maven build under swagger maven plugin.

Installation och installation

I det här avsnittet kommer vi att installera swagger, ställa in swagger-gränssnittet och generera serversidan och klientens SDK med den. Utför följande kommando för att installera swagger med Node-pakethanteraren:

npm install -g swagger

Användning av '-g' flagga kommer att säkerställa att modulen installeras globalt. Därefter skapar vi ett projekt med följande kommando:

swagger project create <project-name>

Detta kommer att be användaren att välja ett ramverk för att utveckla REST-API: erna. Express kan väljas för samma. Detta skapar projektkatalogen med följande objekt och en README.md-fil i var och en av dem:

  • api /
    • controllers /
    • hjälpare /
    • mocks /
    • skryt/
  • config /
  • testa/
    • api /
      • controllers /
      • hjälpare
  • app.js
  • package.json

Servern är i princip klar nu och kan startas med det här kommandot för att köras i projektroten:

swagger project start

Om värdservern är inställd som localhost och portnummer inte ändras i app.js filen, startas servern på: http://localhost:10010 Nu kan swagger-gränssnittet användas för att vidareutveckla våra REST-API: er. Detta kan startas i en ny terminal med:

swagger project edit

Detta öppnar swagger-redigeraren i en webbläsarflik på en slumpmässigt genererad port. Ett exempel på Hej GET-förfrågan kan redan ses i filen swagger.yaml. Varje ytterligare ändring av den här filen får servern att starta om på egen hand.

I vägsektionen bör värdet som används för x-swagger-router-controller vara javascript-filnamnet i mappen controllers. Som ett exempel bör hello_world.js finnas i katalogen för kontroller. Värdet för parametern operationId representerar också funktionsnamnet i ovanstående javascript-fil. Det är här som affärslogik bör skrivas. Således är vår swagger-installation fullständig och kan användas för att vidareutveckla vårt API.