courses:a7b36omo:labs:lab122017

12 - Specifikace API ve Swagger

12 - Specifikace API ve Swagger

Řešení z minulého cvičení

https://gitlab.fel.cvut.cz/B171_B6B36OMO/seminar/tree/master/cv11.1_solution

https://gitlab.fel.cvut.cz/B171_B6B36OMO/seminar/tree/master/cv11.2_solution

https://gitlab.fel.cvut.cz/B171_B6B36OMO/seminar/tree/master/cv11.3_solution

https://gitlab.fel.cvut.cz/B171_B6B36OMO/seminar/tree/master/cv11.4_solution

Teorie

Přednáška:

OpenAPISwagger:

https://swagger.io/getting-started/

https://idratherbewriting.com/learnapidoc/pubapis_swagger_intro.html

Zadání

Připravte specifikace rozhraní komponent knihovního systému, který umožňuje čtenáři online rezervaci vypůjčení knihy ve vybrané čítárně.

Systém umožní vyhledat knihu v inventáři knih, vyhledat a vybrat čítárnu, kde si čtenář knihu vypůjčí a provést rezervaci. Rezervovanou knihu pak knihovna distribuuje z centrálního archivu do konkrétní čítárny, kde ji čtenář dostane k dispozici.

Řešení systému bude v architektonickém stylu microservice. Komunikačním protokolem mezi microservice bude REST API.

Systém bude složený z následujících microservice:

Online Reservation – umožňuje najít knihu v registru centrálního systému, rezervovat knihu, udržuje informace o stavu rezervace

Central Archive – spracuje centrální registr knih, eviduje distribuci knihy do čítárny

Reading Room - eviduje knihy, které přišly z centrálního skladu, spravuje vypůjčení knihy čtenářem

Cílem cvičení není udělat kompletní návrh řešení, ale projít důležité body v použití Swagger pro návrh rozhraní až po vygenerování kódu microservice.

Hlavní body cvičení

Pomocí SwagerHub nadefinujte doménový model knihovního systému a definice REST rozhraní microservice Online Reservation, Central Archive, Reading Room.
Ze SwaggerHub vygenerujte spring projekt a prohlédněte si vygenerovanou implementaci.
Spusťte microservice a vyzkoušejte funkčnost REST API.

Postup

V internetovém prohlížeči otevřete https://app.swaggerhub.com
Zaregistujte se jako nový uživatel SwaggerHub

Vytvořte doménu OMOLibraryDomain

V OMOLibraryDomain
1. nadefinujte objekt Book
2. nadefinujte objekt Reader
3. nadefinujte objekt Address
4. nadefinujte objekt ReadingRoom
5. nadefinujte objekt Reservation

Book:

  description: "Kniha, kterou si může čtenář vypůjčit."
  required:
   - title
   - author
   - isbn
  properties:
   bookId:
    type: integer
   title:
    type: string
   author: 
    type: string
   numberOfPages:
    type: integer
    format: int32
   isbn:
    type: string
    pattern: "^(?:ISBN(?:-10)?:?)?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$)[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$"

Reader:

  description: "Čtenář, který si bude půjčovat knihy."
  required:
   - readerNumber
   - firstname
   - lastname
   - email
  properties:
   readerNumber:
    type: integer
   firstname: 
    type: string
   lastname:
    type: string
   email:
    type: string

Address:

  required:
   - city
   - zipcode
  properties:
   street: 
    type: string
   city:
    type: string
   zipcode:
    type: string
    format: zip-code

ReadingRoom:

  required: 
   - readingRoomId
   - address
  properties:
   readingRoomId:
    type: integer
   address: 
    $ref: "#/definitions/Address"

Reservation:

  required:
    - readerNumber
    - readingRoomId
    - bookId
  properties:
   readerNumber:
    type: integer
   readingRoomId: 
    type: integer
   bookId:
    type: integer

Vytvořte novou definici API – Online Reservation

V API - Online Reservation
1. nadefinujte REST operace GET inventory
2. nadefinujte REST operaci GET readingRoom
3. nadefinujte REST operaci POST, DELETE reservation
4. nadefinujte REST operaci POST bookAvailabitlityDate

/inventory:

  get:
    tags:
    - users
    summary: searches inventory
    operationId: searchInventory
    description: |
      By passing in the appropriate options, you can search for
      available inventory in the system
    produces:
    - application/json
    parameters:
    - in: query
      name: searchString
      description: pass an optional search string for looking up inventory
      required: false
      type: string
    - in: query
      name: skip
      description: number of records to skip for pagination
      type: integer
      format: int32
      minimum: 0
    - in: query
      name: limit
      description: maximum number of records to return
      type: integer
      format: int32
      minimum: 0
      maximum: 50
    responses:
      200:
        description: search results matching criteria
        schema:
          type: array
          items:
            $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Book'
      400:
        description: bad input parameter

/readingRoom:

  get:
    tags:
    - users
    summary: searches reading room
    operationId: searchReadingRoom
    description: Return a list of reading rooms. 
    produces:
    - application/json
    parameters:
    - in: query
      name: searchString
      description: pass an optional search string for looking up reding room
      required: false
      type: string
    - in: query
      name: skip
      description: number of records to skip for pagination
      type: integer
      format: int32
      minimum: 0
    - in: query
      name: limit
      description: maximum number of records to return
      type: integer
      format: int32
      minimum: 0
      maximum: 50
    responses:
      200:
        description: search results matching criteria
        schema:
          type: array
          items:
            $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/ReadingRoom'
      400:
        description: bad input parameter

/reservation:

  post:
    tags:
      - users
    summary: adds a new reservation of book
    operationId: addReservation
    description: reserve a book for reader
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservation
      description: the reservation details
      schema: 
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      409:
        description: an existing item already exists

   delete:
    tags:
      - users
    summary: removes an existing reservation of book
    operationId: deleteReservation
    description: deleta a reservation
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservation
      description: the reservation details
      schema: 
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      410:
        description: a requested item does not exists

/bookAvailability:

  post:
    tags:
      - admins
    summary: posts a date when the book is available in requested reading room
    operationId: postBookAvailability
    description: posts a date when the book is available in requested reading room
    consumes:
      - application/json
    produces:
      - application/json
    parameters:
    - in: body
      name: reservationDate
      schema: 
        $ref: "#/definitions/ReservationDate"
    responses:
      201:
        description: item created
      400:
        description: invalid input, object invalid
      410:
        description: the reservation does not exist

  definitions:
     ReservationDate:
      properties:
        reservation:
          $ref: 'https://api.swaggerhub.com/domains/Tomas-Mayer/OMOLibraryDomain/1.0.0#/definitions/Reservation'
        date:
         type: string
         format: date

Vytvořte specifikaci API Central Archive

Vytvořte definici API Reading Room

Vygenerujte spring server implementaci pro Online Reservation API

Naimportujte vygenerovaný maven projekt do vývojového prostředí

Projděte vygenerovanou implementaci a v třídě InventoryApiController najděte operaci searchInventory, operaci upravte tak, aby vracela seznam knih nejen pro content-type application/json

Spusťte vygenerovanou implementaci příkazem mvn spring-boot:run. Poznamenejte si port, kterém microservice poslouchá (obyčejně 8080).

Ve SwaggerHub spusťte simulaci (Try out a Execute), prohlédněte si vygenerovaný request a očekávaný výsledek.

Request vygenerovaný v předchozím kroku zadejte do internetového prohlížeče. Jako host zadejte localhost a port, na kterém poslouchá spring microservice (například: http://localhost:8080/…….) a zkontrolujte výsledek.

Z http://curl.haxx.se stahněte a nainstalujte curl
Spusťte rest volání pomocí curl příkazu