#LaravelPoznanMeetup #8 Temat: "Laravel dokumentacja Restful API - swagger" Autor: Kamil Kiełczewski (Airavana)

1. Laravel

2. Kamil Kiełczewski
Właściciel
kamil.k.kielczewski@gmail.com
Zdjęcie
prelegenta

3. Agenda
1. Wprowadzenie
2. Przykład
3. Podsumowanie

4. Architektura Mikroserwisowa

5. Architektura Mikroserwisowa

6. Historia
REST (REpresentational State Transfer) - Roy Fielding doktorat "Architectural Styles
and the Design of Network-based Software Architectures" at UC Irvine, 2000
JSON (JavaScript Object Notation) - wyspecyfikowany przez Douglas Crockford
we wczesnych latach 2000
SOAP (Simple Object Access Protocol) : zaprojektowany przez Dave Winer, Don
Box, Bob Atkinson, Mohsen Al-Ghosein dla Microsoft, 1998
XML (eXtensible Markup Language) - wywodzi się z SGML (Charles Goldfarb,
Edward Mosher, Raymond Lorie, IBM, lata 1960), wielu autorów, 1996

7. Restful API - przykład
Metoda URL Opis
GET http://api.local/api/v1/movies zwraca listę filmów
POST http://api.local/api/v1/movies tworzy nowy film (z JSON)
GET http://api.local/api/v1/movies/:id zwraca detale filmu
PUT http://api.local/api/v1/movies/:id aktualizuje film (z JSON)
DELETE http://api.local/api/v1/movies/:id usuwa film

8. Restful API
GET http://api.local/api/v1/movies/123
{
"id": 123,
"title": "Rocky",
"year": 1976,
"genre": "drama",
"oscar": true,
"director": {...}
}

9. Problem
Jak opisywać API?
Gdzie przechowywać opis?

10. Historia
Excel/docks
Wiki / Jira / inne

11. Odpowiedź
Swagger - adnotacje w kodzie!

12. Historia
Swagger (api framewrok) - Tony Tam, 2010; OpenAPI (OA) 2016
Laravel (php framework) - Taylor Otwell, czerwiec 2011
Swagger-PHP (swagger.json gen from doctrine annotations ) styczeń 2015
Swagger-UI (UI gen from swagger.json) czerwiec 2011
DarkaOnLine/L5-Swagger (swagger-ui/php wrapper for L5) marzec 2015

13. Instalacja
laravel new api
cd api
composer require "darkaonline/l5-swagger:5.7.*"
php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"
config => api/config/l5-swagger.php
url => http://laravel-api.local/api/documentation

14. Przykład
.env:
# regenerate always
L5_SWAGGER_GENERATE_ALWAYS= true
/**
* @OAInfo(
* title="Laravel API", version="0.1", description="My api"
* )
*
* @OASecurityScheme(
* securityScheme="oauth2",
* type="oauth2",
* description="OAuth2 Password Grant",
* @OAFlow(
* flow="password",
* authorizationUrl="/oauth/authorize",
* tokenUrl="/oauth/token",
* refreshUrl="/oauth/token/refresh",
* scopes={"*": "ALL scopes"}
* )
* ),
*
* # first request to avoid swagger compilation err
* @OAGet(path="/test", @OAResponse(response="200",
* description="x",
* @OAJsonContent( type="json", example=
* {
* "name":"project",
* "items":{ 5, 6, {"a":1, "b":2, "c":{} } },
* }
* )),
* security={ {"oauth2": {"*"}} },
* )
*/
app/Http/Controllers/Controller.php:

15. Przykład

16. Przykład - konfiguracja
.env:
# sqlite db
DB_* (usuwamy/komentujemy wszystko z prefixem DB_ )
DB_CONNECTION=sqlite (dodajemy wpis)
cmd:
touch database/database.sqlite

17. Przykład - db
php artisan make:model Movie --migration
database/migrations/2018_11_16_230213_create_movies_table.php:
Schema::create('movies' , function (Blueprint $table) {
$table->increments ('id');
$table->unsignedInteger ('director_id' );
$table->string('title');
$table->integer('year');
$table->enum('genre', ['drama', 'comedy' , 'thriller' ]);
$table->boolean('oscar');
$table->timestamps ();
$table->foreign('director_id' )->references ('id')->on('directors' )->onDelete ('cascade' );
});
php artisan make:model Director --migration
database/migrations/2018_11_16_233410_create_directors_table.php:
Schema::create('directors' , function (Blueprint $table) {
$table->increments ('id');
$table->string('first_name' );
$table->string('last_name' );
$table->timestamps ();
});
php artisan migrate

18. Podtytuł 3
php artisan make:controller API/MovieController --api --model=Movie
php artisan make:controller API/DirectorController --api --model=Director
routes/api.php:
Route::group(['prefix'=>'v1'], function() {
Route::apiResource('movies', 'APIMovieController');
Route::apiResource('directors', 'APIDirectorController');
});

19. Przykład
/**
* @OASchema(
* @OAProperty( property="id", type="integer", example=3 ),
* @OAProperty( property="first_name", type="string", example="John" ),
* @OAProperty( property="last_name", type="string", example="Smith" ),
* @OAProperty( property="created_at", type="string", example="2018-10-21 19:13:37" ),
* @OAProperty( property="updated_at", type="string", example="2018-10-31 23:01:34" ),
*
* )
*/
class Director extends Model
{
protected $fillable = ['first_name', 'last_name'];
}
/**
* @OASchema(
* schema="DirectorEdit",
* @OAProperty( property="first_name", ref="#/components/schemas/Director/properties/first_name" ),
* @OAProperty( property="last_name", ref="#/components/schemas/Director/properties/last_name" ),
*
* )
*/
app/Director.php:

20. Przykład

21. Przykład
app/Http/Controllers/API/DirectorController.php
/**
* @OAGet(
* path="/api/v1/directors",
* tags={"director"},
* @OAResponse(response="200", description="list",
* @OAJsonContent( type="array", @OAItems( ref="#/components/schemas/Director" ))
* )
* )
*/
public function index()
{
return Director::all();
}

22. Przykład

23. Podtytuł 3

24. Przykład
app/Http/Controllers/API/DirectorController.php
/**
* @OAPost(
* path="/api/v1/directors",
* tags={"director"},
* @OARequestBody( required=true, @OAJsonContent(ref="#/components/schemas/DirectorEdit")),
* @OAResponse(response="201", description="director", @OAJsonContent( ref="#/components/schemas/Director") )
* )
*/
public function store(Request $request)
{
$director = Director::create($request->all());
return $director;
}

25. Podtytuł 3

26. Podtytuł 3

27. Przykład
app/Http/Controllers/API/DirectorController.php
/**
* @OAGet(
* path="/api/v1/directors/{director_id}", tags={"director"},
* @OAParameter(name="director_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OAResponse(response="200", description="director", @OAJsonContent(ref="#/components/schemas/Director"))
* )
*/
public function show(Director $director)
{
return $director;
}

28. Podtytuł 3

29. Przykład
app/Http/Controllers/API/DirectorController.php
/**
* @OAPut(
* path="/api/v1/directors/{director_id}",
* tags={"director"},
* @OAParameter(name="director_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OARequestBody( required=true, @OAJsonContent(ref="#/components/schemas/DirectorEdit")),
* @OAResponse(response="200", description="director", @OAJsonContent( ref="#/components/schemas/Director") )
* )
*/
public function update(Request $request, Director $director)
{
$director->fill($request->all())->save();
return $director;
}

30. Podtytuł 3

31. Przykład
app/Http/Controllers/API/DirectorController.php
/**
* @OADelete(
* path="/api/v1/directors/{director_id}", tags={"director"},
* @OAParameter(name="director_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OAResponse(response="200", description="director", @OAJsonContent(ref="#/components/schemas/Director"))
* )
*/
public function destroy(Director $director)
{
$director->delete();
return $director;
}

32. Przykład

33. Przykład

34. Przykład
/**
* @OASchema(
* @OAProperty( property="id", type="integer", example=3 ),
* @OAProperty( property="director", ref="#/components/schemas/Director" ),
* @OAProperty( property="title", type="string", example="Rocky" ),
* @OAProperty( property="year", type="integer", example="1976" ),
* @OAProperty( property="genre", type="enum", enum={"drama", "comedy", "thriller"}, example="drama" ),
* @OAProperty( property="oscar", type="boolean", example=true ),
* @OAProperty( property="created_at", type="string", example="2018-10-21 19:13:37" ),
* @OAProperty( property="updated_at", type="string", example="2018-10-31 23:01:34" ),
*
* )
*/
class Movie extends Model
{
protected $fillable = ['director_id','title', 'year','genre','oscar'];
protected $hidden = ['director_id'];
public function director()
{
return $this->belongsTo('AppDirector');
}
}
app/Movie.php:

35. Przykład
/**
* @OASchema(
* schema="MovieEntry",
* @OAProperty( property="id", ref="#/components/schemas/Movie/properties/id" ),
* @OAProperty( property="title", ref="#/components/schemas/Movie/properties/title" ),
* @OAProperty( property="year", ref="#/components/schemas/Movie/properties/year" ),
* @OAProperty( property="genre", ref="#/components/schemas/Movie/properties/genre" ),
* @OAProperty( property="oscar", ref="#/components/schemas/Movie/properties/oscar" ),
* @OAProperty( property="created_at", ref="#/components/schemas/Movie/properties/created_at" ),
* @OAProperty( property="updated_at", ref="#/components/schemas/Movie/properties/updated_at" ),
* )
*/
/**
* @OASchema(
* schema="MovieEdit",
* @OAProperty( property="director_id", type="integer", example="1" ),
* @OAProperty( property="title", ref="#/components/schemas/Movie/properties/title" ),
* @OAProperty( property="year", ref="#/components/schemas/Movie/properties/year" ),
* @OAProperty( property="genre", ref="#/components/schemas/Movie/properties/genre" ),
* @OAProperty( property="oscar", ref="#/components/schemas/Movie/properties/oscar" ),
* )
*/
app/Movie.php:

36. Przykład

37. Przykład
/**
* @OAGet(
* path="/api/v1/movies",
* @OAParameter(name="genre", in="query", @OASchema( type="enum", enum={"drama", "comedy", "thriller"})),
* tags={"movie"},
* @OAResponse(response="200", description="list",
* @OAJsonContent( type="array", @OAItems( ref="#/components/schemas/MovieEntry" ))
* )
* )
*/
public function index()
{
$genre = request()->genre;
if($genre) {
return Movie::where('genre',$genre)->get();
} else {
return Movie::get();
}
}
app/Http/Controllers/API/MovieController.php:

38. Przykład

39. Przykład - multi-wybieralna lista
* @OAParameter(name="genre", in="query",
* @OASchema(
* type="array",
* @OAItems( type="enum", enum={"drama", "comedy", "thriller"} ),
* example={"drama"}
* )
* ),

40. Przykład
/**
* @OAPost(
* path="/api/v1/movies",
* tags={"movie"},
* @OARequestBody( required=true, @OAJsonContent(ref="#/components/schemas/MovieEdit")),
* @OAResponse(response="201", description="director", @OAJsonContent( ref="#/components/schemas/Movie") )
* )
*/
public function store(Request $request)
{
$director = Director::findOrFail($request->director_id);
$movie = Movie::create($request->all());
return $movie;
}
app/Http/Controllers/API/MovieController.php:

41. Przykład

42. Przykład
/**
* @OAGet(
* path="/api/v1/movies/{movie_id}", tags={"movie"},
* @OAParameter(name="movie_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OAResponse(response="200", description="director", @OAJsonContent(ref="#/components/schemas/Movie"))
* )
*/
public function show(Movie $movie)
{
$movie->director; // load director to movie object
return $movie;
}
app/Http/Controllers/API/MovieController.php:

43. Przykład

44. Przykład
/**
* @OAPut(
* path="/api/v1/movies/{movie_id}",
* tags={"movie"},
* @OAParameter(name="movie_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OARequestBody( required=true, @OAJsonContent(ref="#/components/schemas/MovieEdit")),
* @OAResponse(response="200", description="director", @OAJsonContent( ref="#/components/schemas/Movie") )
* )
*/
public function update(Request $request , Movie $movie)
{
$movie->fill($request ->all())->save();
return $movie;
}
/**
* @OADelete(
* path="/api/v1/movies/{movie_id}", tags={"movie"},
* @OAParameter(name="movie_id", required=true, in="path", @OASchema( type="integer", example=1 ) ),
* @OAResponse(response="200", description="director", @OAJsonContent(ref="#/components/schemas/MovieEntry"))
* )
*/
public function destroy(Movie $movie)
{
$movie->delete();
return $movie;
}
app/Http/Controllers/API/MovieController.php:

45. Przykład

46. Przykład

47. Przykład - swagger.json
{"openapi":"3.0.0","info":{"title":"Laravel API","description":"My
api","version":"0.1"},"paths":{"/api/v1/directors":{"get":{"tags":["director"],"operationId":"AppHttpControllersAPIDirectorController::index","responses":{"200":{"description":"list","content":{"a
pplication/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Director"}}}}}}},"post":{"tags":["director"],"operationId":"AppHttpControllersAPIDirectorController::store","re
questBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectorEdit"}}}},"responses":{"201":{"description":"director","content":{"application/json":{"sc
hema":{"$ref":"#/components/schemas/Director"}}}}}}},"/api/v1/directors/{director_id}":{"get":{"tags":["director"],"operationId":"AppHttpControllersAPIDirectorController::show","parameters":
[{"name":"director_id","in":"path","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/compone
nts/schemas/Director"}}}}}},"put":{"tags":["director"],"operationId":"AppHttpControllersAPIDirectorController::update","parameters":[{"name":"director_id","in":"path","required":true,"schema
":{"type":"integer","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectorEdit"}}}},"responses":{"200":{"description":"direct
or","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Director"}}}}}},"delete":{"tags":["director"],"operationId":"AppHttpControllersAPIDirectorController::destroy","para
meters":[{"name":"director_id","in":"path","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/c
omponents/schemas/Director"}}}}}}},"/api/v1/movies":{"get":{"tags":["movie"],"operationId":"AppHttpControllersAPIMovieController::index","parameters":[{"name":"genre","in":"query","sche
ma":{"type":"array","items":{"type":"enum","enum":["drama","comedy","thriller"]},"example":["drama"]}}],"responses":{"200":{"description":"list","content":{"application/json":{"schema":{"type":"arr
ay","items":{"$ref":"#/components/schemas/MovieEntry"}}}}}}},"post":{"tags":["movie"],"operationId":"AppHttpControllersAPIMovieController::store","requestBody":{"required":true,"content":
{"application/json":{"schema":{"$ref":"#/components/schemas/MovieEdit"}}}},"responses":{"201":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/components/schemas/
Movie"}}}}}}},"/api/v1/movies/{movie_id}":{"get":{"tags":["movie"],"operationId":"AppHttpControllersAPIMovieController::show","parameters":[{"name":"movie_id","in":"path","required":true,"
schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Movie"}}}}}},"put":{"tags":["movie"],"
operationId":"AppHttpControllersAPIMovieController::update","parameters":[{"name":"movie_id","in":"path","required":true,"schema":{"type":"integer","example":1}}],"requestBody":{"requir
ed":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieEdit"}}}},"responses":{"200":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/com
ponents/schemas/Movie"}}}}}},"delete":{"tags":["movie"],"operationId":"AppHttpControllersAPIMovieController::destroy","parameters":[{"name":"movie_id","in":"path","required":true,"schem
a":{"type":"integer","example":1}}],"responses":{"200":{"description":"director","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieEntry"}}}}}}},"/test":{"get":{"responses
":{"200":{"description":"x","content":{"application/json":{"schema":{"type":"json"},"example":{"name":"project","items":[5,6,{"a":1,"b":2,"c":[]}]}}}}},"security":[{"oauth2":["*"]}]}}},"components":{"sche
mas":{"Director":{"properties":{"id":{"type":"integer","example":3},"first_name":{"type":"string","example":"John"},"last_name":{"type":"string","example":"Smith"},"created_at":{"type":"string","exa
mple":"2018-10-21 19:13:37"},"updated_at":{"type":"string","example":"2018-10-31
23:01:34"}},"type":"object"},"DirectorEdit":{"properties":{"first_name":{"$ref":"#/components/schemas/Director/properties/first_name"},"last_name":{"$ref":"#/components/schemas/Director/prop
erties/last_name"}},"type":"object"},"Movie":{"properties":{"id":{"type":"integer","example":3},"director":{"$ref":"#/components/schemas/Director"},"title":{"type":"string","example":"Rocky"},"year":
{"type":"integer","example":"1976"},"genre":{"type":"enum","enum":["drama","comedy","thriller"],"example":"drama"},"oscar":{"type":"boolean","example":true},"created_at":{"type":"string","exam
ple":"2018-10-21 19:13:37"},"updated_at":{"type":"string","example":"2018-10-31
23:01:34"}},"type":"object"},"MovieEntry":{"properties":{"id":{"$ref":"#/components/schemas/Movie/properties/id"},"title":{"$ref":"#/components/schemas/Movie/properties/title"},"year":{"$ref":"#/c
omponents/schemas/Movie/properties/year"},"genre":{"$ref":"#/components/schemas/Movie/properties/genre"},"oscar":{"$ref":"#/components/schemas/Movie/properties/oscar"},"created_at":{"
$ref":"#/components/schemas/Movie/properties/created_at"},"updated_at":{"$ref":"#/components/schemas/Movie/properties/updated_at"}},"type":"object"},"MovieEdit":{"properties":{"director_id
":{"type":"integer","example":"1"},"title":{"$ref":"#/components/schemas/Movie/properties/title"},"year":{"$ref":"#/components/schemas/Movie/properties/year"},"genre":{"$ref":"#/components/sch
emas/Movie/properties/genre"},"oscar":{"$ref":"#/components/schemas/Movie/properties/oscar"}},"type":"object"}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2
Password Grant","flows":{"password":{"authorizationUrl":"/oauth/authorize","tokenUrl":"/oauth/token","refreshUrl":"/oauth/token/refresh","scopes":{"*":"ALL scopes"}}}}}}}

48. Podsumowanie
Plusy opisywania API za pomocą swaggera w L5:
1. Wersjonowanie opisu (git)
2. Wszystko pod ręką (w kodzie)
3. Publikowanie opisu API bezpośrednio w aplikcji
4. Generyczne UI dla ręcznego testowania API
5. Generowanie swagger JSON/YAML dla innych narzędzi
(np. testowania automatycznego, generowania klientów
api dla angular etc.)
6. Wsparcie dla oauth2

49. Bonus - Pozycja
Krzesło - pomyłka...

50. Bonus - Pozycja
Piłka 55cm (~50zł)
Prosta pozycja:
- zdrowy kręgosłup
- głębszy oddech (wydech)
- lepsze krążenie
- brak nacisku na narz. wew.
- więcej energii
Prosta pozycja wywoła na początku ból
nieprzyzwyczajonych mięśni. Oswajanie się:
1 tydzień - 15 min/dziennie,
2 tydzien - 30 min/dziennie,
...
6 tydzień - 8 godz/dziennie
- Wyciągamy czubek głowy by “podnieść nim sufit”
- Broda nisko, blisko szyi.
- Uszy równo z barkami a nos w linii z pępkiem
- Kolana niżej niż biodra
- Brzuch blisko krawędzi biurka
- Brak oparcia dla pleców, ekran centralnie z przodu
- Czubek ekranu na wysokości czubka głowy-wzroku
- Piłka mocno napompowana
wzorcowo

51. Bonus - Pozycja
Piłka - Błędy
- za daleko od stołu
(powoduje z czasem
pochylenie do przodu)
- miękka piłka
- za nisko ekran
- za nisko ekran
powoduje z czasem
zginanie szyi w dół
- ekran z boku
- za daleko od stołu
- miękka piłka

52. Bonus - Pozycja

53. Podsumowanie
Pytania?
Ta prezentacja: https://is.gd/QTjqXE

54. Kamil Kiełczewski
kamil.k.kielczewski@gmail.com
airavana.net