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).
- https://github.com/DarkaOnLine/L5-Swagger
- $ composer require « darkaonline/l5-swagger:5.7.* »
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