Tutoriel vidéo : une introduction à Swagger
Le code PHP pour votre projet Laravel 5
Cette section présente le code PHP Laravel pour les classes suivantes :
Controller.php
StationController.php
PostStationRequest.php
StationResource.php
Portez une attention particulière aux commentaires qui comportent des annotations qui serviront à la création de la documentation interactive Swagger.
Le projet utilisé se nomme L5-Swagger (Swagger pour Laravel 5).
La classe contrôleur de base
Nous définissons les paramètres de base pour la documentation interactive.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<?php
namespace App \ Http \ Controllers ;
use Illuminate \ Foundation \ Bus \ DispatchesJobs ;
use Illuminate \ Routing \ Controller as BaseController ;
use Illuminate \ Foundation \ Validation \ ValidatesRequests ;
use Illuminate \ Foundation \ Auth \ Access \ AuthorizesRequests ;
/**
* @OA\Info(
* version="1.0.2",
* title="Documentation des services Web",
* description="Documentation pour le projet de développement de services Web.
* Tutoriels sur Atomrace.com",
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
*
* @OA\Server(
* url=L5_SWAGGER_CONST_HOST,
* description="Serveur"
* )
*
* @OA\SecurityScheme(
* type="oauth2",
* securityScheme="Oauth2Password",
* name="Password Based",
* scheme="bearer",
* description="Utilisez client_id / client_secret et
* votre courriel / mot de passe pour
* obtenir un jeton d'authentification.",
* in="header",
* @OA\Flow(
* flow="password",
* authorizationUrl="/oauth/authorize",
* tokenUrl="/oauth/token",
* refreshUrl="/oauth/token/refresh",
* scopes={}
* )
* )
*/
class Controller extends BaseController
{
use AuthorizesRequests , DispatchesJobs , ValidatesRequests ;
}
Contrôleur pour la gestion de stations d’analyse de qualité de l’air
Ici, 2 routes sont définies. Une route GET et une autre POST. Notez que la route POST est protégée par un security scheme .
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
/**
* Display a listing of the resource.
*
* @return \Illuminate\Http\Response
*
* @OA\Get(
* path="/api/stations",
* tags={"Station"},
* @OA\Parameter(
* name="page",
* description="Page number",
* required=false,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response="200",
* description="Returns the stations collection",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Station")
* )
* )
* )
*/
public function index ( )
{
$stations = Station:: paginate ( 5 ) ;
return StationResource:: collection ( $stations ) ;
}
/**
* Store a newly created resource in storage.
* @OA\Post(
* tags={"Station"},
* path="/api/stations",
* security={ { "Oauth2Password": {} } },
* @OA\Response(
* response="201",
* description="Returns the created station",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Station")
* )
* ),
* @OA\RequestBody(
* description="Station to create",
* required=true,
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(ref="#/components/schemas/StationPostRequest")
* )
* )
* )
*
* @param \App\Http\Requests\StationPostRequest $request
* @return \Illuminate\Http\Response
*/
public function store ( StationPostRequest $request )
{
$station = new Station ( $request -> all ( ) ) ;
if ( $station -> save ( ) ) {
return new StationResource ( $station ) ;
}
}
Définition d’une classe de validation FormRequest
Cette section permet de définir les règles de validation pour notre requête POST.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?php
namespace App \ Http \ Requests ;
use Illuminate \ Foundation \ Http \ FormRequest ;
/**
* @OA\Schema(schema="StationPostRequest")
* {
* @OA\Property(
* property="name",
* type="string",
* description="The station name"
* ),
* @OA\Property(
* property="title",
* type="string",
* description="The station title"
* )
* }
*/
class StationPostRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
*
* @return bool
*/
public function authorize ( )
{
return true ;
}
/**
* Get the validation rules that apply to the request.
*
* @return array
*/
public function rules ( )
{
return [
'name' = > 'filled|required|string' ,
'description' = > 'filled|string' ,
'long' = > 'filled|required|numeric' ,
'lat' = > 'filled|required|numeric' ,
'user_id' = > 'filled|required' ,
] ;
}
}
Ressource ou structure des données retournées au client
La classe StationResource permet de définir les données qui seront retournées au client.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
<?php
namespace App \ Http \ Resources ;
use Illuminate \ Http \ Resources \ Json \ Resource ;
/**
* @OA\Schema(schema="Station")
* {
* @OA\Property(
* property="name",
* type="string",
* description="The station name"
* ),
* @OA\Property(
* property="title",
* type="string",
* description="The station title"
* ),
* @OA\Property(
* property="lat",
* type="number",
* format="float",
* description="The station latitude"
* ),
* @OA\Property(
* property="long",
* type="number",
* format="float",
* description="The station longitude"
* )
* }
*/
class StationResource extends Resource
{
/**
* Transform the resource into an array.
*
* @param \Illuminate\Http\Request $request
* @return array
*/
public function toArray ( $request )
{
return [
'id' = > $this -> id ,
'name' = > $this -> name ,
'description' = > $this -> description ,
'long' = > $this -> long ,
'lat' = > $this -> lat
] ;
}
}
nice