===== 12 - Specifikace API ve Swagger =====
==== Řešení z minulého cvičení ====
[[https://gitlab.fel.cvut.cz/B181_B6B36OMO/seminar/tree/master/cv11.1_solution]]
[[https://gitlab.fel.cvut.cz/B181_B6B36OMO/seminar/tree/master/cv11.2_solution]]
[[https://gitlab.fel.cvut.cz/B181_B6B36OMO/seminar/tree/master/cv11.3_solution]]
[[https://gitlab.fel.cvut.cz/B181_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
{{:courses:a7b36omo:labs:cv12_omolibrary.png?500|}}
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
{{ :courses:a7b36omo:labs:cv12_swagger_hub_1.png?700 |}}
* Vytvořte doménu OMOLibraryDomain
{{ :courses:a7b36omo:labs:cv12_swagger_hub_2.png?700 |}}
* V OMOLibraryDomain v sekci **definitions:**
- nadefinujte objekt Book
- nadefinujte objekt Reader
- nadefinujte objekt Address
- nadefinujte objekt ReadingRoom
- nadefinujte objekt Reservation
Book
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
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
Address:
required:
- city
- zipcode
properties:
street:
type: string
city:
type: string
zipcode:
type: string
format: zip-code
ReadingRoom
ReadingRoom:
required:
- readingRoomId
- address
properties:
readingRoomId:
type: integer
address:
$ref: "#/definitions/Address"
Reservation
Reservation:
required:
- readerNumber
- readingRoomId
- bookId
properties:
readerNumber:
type: integer
readingRoomId:
type: integer
bookId:
type: integer
* Vytvořte novou definici API – Online Reservation
{{ :courses:a7b36omo:labs:cv12_swagger_hub_3.png?700 |}}
* V API - Online Reservation
- nadefinujte REST operace GET inventory
- nadefinujte REST operaci GET readingRoom
- nadefinujte REST operaci POST, DELETE reservation
- 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
{{ :courses:a7b36omo:labs:cv12_swagger_hub_4.png?nolink&800 |}}
* Vytvořte specifikaci API Central Archive
{{ :courses:a7b36omo:labs:cv12_swagger_hub_5.png?nolink&800 |}}
* Vytvořte definici API Reading Room
{{ :courses:a7b36omo:labs:cv12_swagger_hub_6.png?nolink&800 |}}
* Přejděte zpět do Online Reservation API a vygenerujte spring server implementaci: V menu Export - Server Stub vyberte Spring.
{{ :courses:a7b36omo:labs:cv12_swagger_hub_7.png?nolink&800 |}}
* Naimportujte vygenerovaný maven projekt do vývojového prostředí
{{ :courses:a7b36omo:labs:cv12_omo_library_1.png?nolink&800 |}}
* 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
{{ :courses:a7b36omo:labs:cv12_omo_library_2.png?nolink&800 |}}
* Spusťte vygenerovanou implementaci příkazem mvn spring-boot:run. Poznamenejte si port, kterém microservice poslouchá (obyčejně 8080).
{{ :courses:a7b36omo:labs:cv12_omo_library_3.png?nolink&800 |}}
* Ve SwaggerHub spusťte simulaci (Try out a Execute), prohlédněte si vygenerovaný request a očekávaný výsledek.
{{ :courses:a7b36omo:labs:cv12_omo_library_4.png?nolink&800 |}}
{{ :courses:a7b36omo:labs:cv12_omo_library_5.png?nolink&800 |}}
{{ :courses:a7b36omo:labs:cv12_omo_library_6.png?nolink&800 |}}
* 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.
{{ :courses:a7b36omo:labs:cv12_omo_library_7.png?nolink&700 |}}
* Z http://curl.haxx.se stahněte a nainstalujte curl
* Spusťte rest volání pomocí curl příkazu
{{ :courses:a7b36omo:labs:cv12_omo_library_8.png?nolink&700 |}}