En savoir plus sur l'utilisation de Laravel Swagger

Cet article vous apporte des connaissances pertinentes sur laravel, qui présente principalement les problèmes liés à l'utilisation de Swagger. Jetons un coup d'œil à la génération de swagger basée sur Laravel à titre d'exemple.

【Recommandation connexe : tutoriel vidéo laravel】

swagger est trop épicé ?

Ce tutoriel est basé sur Laravel générant swagger comme exemple. En fait, cette chose est fondamentalement la même qu'un langage ou un framework, car ils utilisent tous du json public. Le "langage" prédéterminé par swagger est analysé via le programme. , et la structure générée est stockée json, affichée via swagger ui (ou développée par vous-même).

Pour les développeurs PHP, la plupart des étudiants n'aiment pas l'arrogance. Parce que cela semble être très difficile à écrire. Quand je pense au code qui peut être écrit en PHP en quelques minutes, il faut 10 minutes pour écrire swagger, et je me sens opposé à cette chose.

Les étudiants impliqués dans le développement Java sauront que la plupart d'entre eux utilisent swagger, car Java doit maintenir la structure des données et swagger est plus flexible à intégrer en Java.

À l'heure actuelle, si vous voyez php en Java dire que le swagger est anti-humain, ce sera trop gênant. C'est un produit des temps anciens. Les amis Java autour de vous seront secrètement heureux de ne pas utiliser des choses aussi utiles, et ils disent aussi que PHP est le meilleur langage au monde.

Pourquoi utiliser swagger

J'ai récemment écrit la génération automatique de code. En fait, Laravel génère désormais automatiquement CURD. Par exemple, l'échafaudage API de overtrue (zhengchao) est également très bonlaravel-admin ，一条命令生成CURD，但是生成之后，数据看上去很冷。 比如有一些字段不需要显示，有一些是要select关联枚举的，有一些是 hasMany

donc swaager peut également écrire une génération automatisée en fonction des besoins de l'entreprise

L5-Swagger

https://github.com/DarkaOnLine/ L5-Swagger

Installation :

composer require "darkaonline/l5-swagger"

Utilisation :

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
php artisan l5-swagger:generate

Remplissez l'exemple suivant pour générer puis accéder

/api/documentation

@OAInfo est requis

Exemple

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="L5 OpenApi",
 *      description="L5 Swagger OpenApi description",
 *      @OA\Contact(
 *          email="darius@matulionis.lt"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */

get request

Si vous souhaitez faire correspondre la valeur dans le chemin, requête dans le chemin dans la requête

/**
 * @OA\Get(
 *      path="/projects/{id}",
 *      operationId="getProjectById",
 *      tags={"Projects"},
 *      summary="Get project information",
 *      description="Returns project data",
 *      @OA\Parameter(
 *          name="id",
 *          description="Project id",
 *          required=true,
 *          in="path",
 *          @OA\Schema(
 *              type="integer"
 *          )
 *      ),
 *      @OA\Response(
 *          response=200,
 *          description="successful operation"
 *       ),
 *      @OA\Response(response=400, description="Bad request"),
 *      @OA\Response(response=404, description="Resource Not Found"),
 *      security={
 *         {
 *             "oauth2_security_example": {"write:projects", "read:projects"}
 *         }
 *     },
 * )
 */

Requête POST

              
    /**
     * @OA\Post(
     *      path="/api/test/store",
     *      operationId="api/test/store",
     *      tags={"Test"},
     *      summary="Test创建",
     *      description="Test提交创建",
     *      @OA\Parameter(
     *          name="id",
     *          description="",
     *          required=false,
     *          in="query",
     *      ),
     *     @OA\Response(
     *         response=200,
     *         description="successful operation",
     *         @OA\JsonContent(
     *         ref="#/components/schemas/Test"
     *         )
     *     ),
     *      @OA\Response(response=400, description="Bad request"),
     *      @OA\Response(response=404, description="Resource Not Found"),
     *      security={
     *         {
     *             "api_key":{}
     *         }
     *     },
     * )
     */

paramètres de téléchargement de fichier

     *     @OA\RequestBody(
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(
     *               type="object",
     *               @OA\Property(
     *                  property="file",
     *                  type="file",
     *               ),
     *           ),
     *       )
     *     ),

passer en tant qu'énumération

     *     @OA\Parameter(
     *         name="status",
     *         in="query",
     *         description="状态",
     *         required=true,
     *         explode=true,
     *         @OA\Schema(
     *             type="array",
     *             default="available",
     *             @OA\Items(
     *                 type="string",
     *                 enum = {"available", "pending", "sold"},
     *             )
     *         )
     *     ),

Le corps est soumis de manière Json

     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="application/json",
     *             @OA\Schema(
     *                 @OA\Property(
     *                     property="id",
     *                     type="string"
     *                 ),
     *                 @OA\Property(
     *                     property="name",
     *                     type="string"
     *                 ),
     *                 example={"id": 10, "name": "Jessica Smith"}
     *             )
     *         )
     *     ),

utiliser la structure Schéma comme paramètre de requête

     *     @OA\RequestBody(
     *         description="order placed for purchasing th pet",
     *         required=true,
     *         @OA\JsonContent(ref="#/components/schemas/UserModel")
     *     ),

L'utilisation du schéma

/**
 * @OA\Schema(
 *      schema="UserModel",
 *      required={"username", "age"},
 *      @OA\Property(
 *          property="username",
 *          format="string",
 *          description="用户名称",
 *          example="小廖",
 *      ),
 *      @OA\Property(
 *          property="age",
 *          format="int",
 *          description="年龄",
 *          example=1,
 *          nullable=true,
 *      )
 * )
 */

Énumération

Une énumération crée un schéma

/**
 * @OA\Schema(
 *   schema="product_status",
 *   type="string",
 *   description="The status of a product",
 *   enum={"available", "discontinued"},
 *   default="available"
 * )
 */

mappé à des champs spécifiques dans le modèle

 *      @OA\Property(
 *     property="status",
 *     ref="#/components/schemas/product_status"
 *      ),

afin que les développeurs front-end puissent

associer le modèle

est similaire à une énumération , via un modèle associé à la propriété

 *      @OA\Property(
 *     property="user_detail",
 *     ref="#/components/schemas/UserModel2"
 *      ),

Modèle et énumération associés, peut générer automatiquement les paramètres demandés et la structure renvoyée

est renvoyée en tant que structure du modèle

     *     @OA\Response(
     *         response=200,
     *         description="successful operation",
     *         @OA\JsonContent(
     *             type="array",
     *             @OA\Items(ref="#/components/schemas/UserModel"),
     *             @OA\Items(ref="#/components/schemas/UserModel2")
     *         )
     *     ),

Tout comme le jour où la fille du front-end vous l'a dit, frère , que signifie le statut de paiement 3 ? , peut-être avez-vous rapidement dit qu'il s'agissait d'un certain état, mais si je vous demandais quel était l'état 11, les gens seraient confus.

Grâce au schéma de swagger, le personnel front-end peut découvrir les informations structurelles du back-end, telles que :

Tout le monde, celles-ci peuvent être programmées automatiquement et générées automatiquement, donc l'efficacité du travail n'est pas trop bonne

Plusieurs schémas fusionnés

/**
 * @OA\Schema(
 *   schema="UserModel",
 *   allOf={
 *     @OA\Schema(ref="#/components/schemas/UserModel2"),
 *     @OA\Schema(
 *       type="object",
 *       description="Represents an authenticated user",
 *       required={
 *         "email",
 *         "role",
 *       },
 *       additionalProperties=false,
 *       @OA\Property(
 *         property="email",
 *         type="string",
 *         example="user@example.com",
 *         nullable=true,
 *       ),
 *     )
 *   }
 * )
 */

Vérification Fournissez deux méthodes : outh2 et apikey, écrivez dans la configuration globale (peut également être dans n'importe quel répertoire)

/**
 * @OA\SecurityScheme(
 *     type="apiKey",
 *     in="query",
 *     securityScheme="api_key",
 *     name="api_key"
 * )
 */

Ajoutez

security={{"api_key": {}}},

dans l'interface

À ce moment, une chose ressemblant à un verrou apparaîtra dans l'interface utilisateur swagger

OK Entrez votre propre jeton, et le jeton sera apporté lors de la demande

Vous pouvez le combiner avec la propre vérification du jeton de Laravel, vous pouvez vous référer à l'article que j'ai écrit avant la garde de Laravel Garde de chrysanthème

Pour plus de méthodes d'utilisation, vous pouvez consulter l'exemple du site officiel : https://github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0

Problèmes que vous pourriez rencontrer

Si vous ne pouvez pas accéder à l'environnement en ligne, il peut s'agir d'un problème avec votre configuration nginx, car laravel-swagger fait écho à la sortie js via file_content_get(). À en juger par votre configuration nginx, s'il s'agit d'un fichier .js ou css, il s'agit d'un fichier statique, donc index.php ne peut pas être atteint et la fonction file_content_get ne peut pas être exécutée. Vous pouvez vous référer à la configuration de nginx :

charset utf-8;
client_max_body_size 128M;

location / {
	try_files $uri $uri/ /index.php$is_args$args;
}


location ~ \.php$ {
	include fastcgi_params;
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	fastcgi_pass  php74:9000 这个换成你自己的;
	try_files $uri =404;
}

[Recommandations associées : tutoriel vidéo laravel]

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!