Swagger :: documentation interactive pour vos services Web

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.

<?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.

/**
* 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.

<?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.

<?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
    ];
 }
}