Laravel Swagger 사용에 대해 자세히 알아보세요.

이 글은 Swagger 사용과 관련된 문제를 주로 소개하는 laravel에 대한 관련 지식을 제공하며, Laravel을 기반으로 Swagger를 생성하는 예제를 살펴보겠습니다.

【관련 추천: laravel 동영상 튜토리얼】

swagger가 너무 매워요?

이 튜토리얼은 Laravel이 Swagger를 생성하는 것을 예로 기반으로 합니다. 실제로 이것은 모두 공개 json을 사용하기 때문에 기본적으로 Swagger에서 미리 결정한 "언어"를 프로그램을 통해 스캔합니다. , 생성된 구조는 json에 저장되고, swagger ui를 통해 표시됩니다(또는 직접 개발).

PHP 개발자의 경우 대부분의 학생들은 swagger를 싫어합니다. PHP로 몇 분 만에 작성할 수 있는 코드를 생각하면 swagger를 작성하는 데 10분이 걸리고 마음속으로는 이 일을 거부합니다.

Java 개발에 참여하는 학생들은 대부분 swagger를 사용한다는 것을 알게 될 것입니다. 왜냐하면 Java는 데이터 구조를 유지해야 하고 swagger는 Java에 통합하는 데 더 유연하기 때문입니다.

이때 자바에서 swagger가 반인륜적이라고 하는 PHP를 보면 너무 귀찮을 겁니다. 당신 주변의 자바 친구들은 이런 유용한 것들을 사용하지 않는다는 사실에 은근히 기뻐할 것이고, 또한 PHP가 세계 최고의 언어라고 말할 것입니다.

swagger를 사용하는 이유

저는 최근에 자동 코드 생성을 작성해 왔습니다. 실제로 Laravel은 이제 자동으로 CURD를 생성합니다. 예를 들어, overtrue(zhengchao)의 API 스캐폴딩도 매우 좋습니다laravel-admin ，一条命令生成CURD，但是生成之后，数据看上去很冷。 比如有一些字段不需要显示，有一些是要select关联枚举的，有一些是 hasMany

그래서 swaager는 비즈니스 요구에 따라 자동 생성도 작성할 수 있습니다

L5-Swagger

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

설치:

composer require "darkaonline/l5-swagger"

사용:

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

생성한 다음

/api/documentation

@OAInfo에 액세스하려면 다음 예를 입력하세요.

예제

/**
 * @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"
 *     )
 * )
 */

요청 받기

경로의 값과 일치시키려면, 쿼리 경로의 쿼리

/**
 * @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"}
 *         }
 *     },
 * )
 */

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":{}
     *         }
     *     },
     * )
     */

파일 업로드 매개변수

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

가 열거형으로 전달됨

     *     @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"},
     *             )
     *         )
     *     ),

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"}
     *             )
     *         )
     *     ),

구조 스키마를 요청 매개변수로 사용

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

스키마

/**
 * @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,
 *      )
 * )
 */

열거

열거는 모델의 특정 필드에 대한 스키마

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

맵을 생성하므로

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

프런트 엔드 개발자가

모델을 연결할 수 있도록

열거와 유사합니다. , 부동산 연관 모델을 통해

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

연관 모델과 열거형은 요청된 매개변수와 반환된 구조

가 모델 구조로 반환됩니다

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

프런트 엔드 소녀가 당신에게 말한 날처럼, 형제님, 결제 상태 3이 무슨 뜻인가요? , 특정 상태라고 금방 말했을 수도 있지만, 상태 11이 무엇인지 물으면 사람들은 혼란스러워할 것입니다.

swagger의 스키마를 통해 프런트엔드 담당자는 다음과 같은 백엔드의 구조 정보를 알아낼 수 있습니다.

누구나 자동으로 프로그래밍할 수 있고 자동 생성되므로 작업 효율이 그리 좋지 않습니다

다중 병합된 스키마

/**
 * @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,
 *       ),
 *     )
 *   }
 * )
 */

검증 outh2와 apikey 두 가지 방법 제공, 전역 구성에 쓰기(어느 디렉토리에도 가능)

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

인터페이스에

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

추가

이때 자물쇠 같은 것이 나타납니다 in the swagger Ui

Okay 자신만의 토큰을 입력하면 요청 시 토큰을 가져옵니다

라라벨 자체 토큰 검증과 결합할 수 있으며, 라라벨 가드 이전에 제가 쓴 글을 참고하시면 됩니다. Chrysanthemum Guardian

더 많은 사용 방법은 공식 웹사이트 예시를 확인하세요: https://github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0

발생할 수 있는 문제

온라인 환경에 접근할 수 없다면 nginx 구성에 문제가 있을 수 있습니다. 왜냐하면 laravel-swagger는 file_content_get()을 통해 js 출력을 에코하기 때문입니다. nginx 구성으로 판단하면 .js 또는 css 파일인 경우 정적 파일이므로 index.php에 접근할 수 없으며 file_content_get 함수를 실행할 수 없습니다. 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;
}

[관련 권장 사항: laravel 비디오 튜토리얼]

위 내용은 Laravel Swagger 사용에 대해 자세히 알아보세요.의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!