Lumen框架下Swagger-PHP生成swagger.json时定义缺失及语法错误问题

Hey fellow dev, let’s break down the two problems you’re facing— that pesky syntax error and the missing definitions node— especially since your models live in a vendor-like custom namespace.

1. Fixing the "[Syntax Error] Expected Value, got '@'" Error #

This error almost always boils down to wonky Swagger annotation syntax in your controller code. Here’s what to check first:

• Double-check your docblock structure: Make sure all @OA\* annotations are wrapped properly in /** ... */ blocks, not single-line // comments or malformed multi-line comments. A common slip-up is forgetting the closing */ or misplacing brackets inside annotations:

  // Wrong: Missing closing docblock tag
  /**
  * @OA\Get(
  *     path="/api/users",
  *     @OA\Response(response="200", description="Success")
  // Oops, no closing */ here!
  

• Validate annotation formatting: Ensure every annotation property is correctly structured— no missing commas, unquoted string values, or misplaced symbols. For example, when defining a path parameter, follow this clean format:

  // Correct example
  /**
  * @OA\Get(
  *     path="/api/users/{id}",
  *     @OA\Parameter(
  *         name="id",
  *         in="path",
  *         required=true,
  *         @OA\Schema(type="integer")
  *     ),
  *     @OA\Response(
  *         response=200,
  *         description="Fetch user details",
  *         @OA\JsonContent(ref="#/definitions/User")
  *     )
  * )
  */
  

• Avoid conflicting comments: If you have regular notes inside your docblocks, don’t use @ symbols— those can confuse Swagger-PHP’s parser. Stick to plain text comments without the @ prefix.

2. Getting the "definitions" Node to Appear (Custom Namespace Models) #

Since your models are in a vendor-style namespace, Swagger-PHP isn’t automatically scanning them. Let’s fix that:

• Add @OA\Schema annotations to your models: Every model you want included in definitions needs this annotation at the top. Even with a custom namespace, the annotation should live in the model’s docblock:

  <?php
  namespace Vendor\YourCustomNamespace\Models;
  
  /**
  * @OA\Schema(
  *     schema="User",
  *     title="User Model",
  *     description="Core user data model",
  *     @OA\Property(property="id", type="integer", example=1),
  *     @OA\Property(property="name", type="string", example="Jane Doe"),
  *     @OA\Property(property="email", type="string", format="email", example="jane@example.com")
  * )
  */
  class User extends \Illuminate\Database\Eloquent\Model
  {
      // Model logic here
  }
  

• Tell Swagger-PHP to scan your custom namespace: When you run the Swagger-PHP command, explicitly include the path to your model directory. For example, if your models are in app/Vendor/YourCustomNamespace/Models, run:

  ./vendor/bin/openapi app/Http/Controllers app/Vendor/YourCustomNamespace/Models -o public/swagger.json
  

  This ensures the parser checks both your controllers and the custom model folder.
• Confirm autoloading works for your namespace: Head to your composer.json and make sure your custom namespace is mapped in the autoload section:

  "autoload": {
      "psr-4": {
          "App\\": "app/",
          "Vendor\\YourCustomNamespace\\": "app/Vendor/YourCustomNamespace/"
      }
  }
  

  After updating, run composer dump-autoload to refresh the autoloader so Lumen (and Swagger-PHP) can find your models.

3. Quick Extra Checks #

• Update Swagger-PHP: Outdated versions can have bugs with custom namespaces or annotation parsing. Grab the latest stable version with:

  composer require zircote/swagger-php:^4.0
  

• Validate your generated JSON: Once you get a swagger.json file, use a local Swagger validation tool or the built-in checker in Swagger UI to make sure there are no hidden issues.

内容的提问来源于stack exchange，提问作者Jose Enrique Lopez