PHP L5-Swagger 예시

L5-Swagger

BookController

Get all books

• URL: /api/books
• Method: GET
• Description: Get all books

/**
 * @OA\Get(
 *     path="/api/books",
 *     tags={"Books"},
 *     summary="Get all books",
 *     @OA\Response(
 *         response=200,
 *         description="Returns all books",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Book")
 *         ),
 *     ),
 * )
 */
public function index()
{
    return Book::all();
}

Create a new book

• URL: /api/books
• Method: POST
• Description: Create a new book

/**
 * @OA\Post(
 *     path="/api/books",
 *     tags={"Books"},
 *     summary="Create a new book",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/Book")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="Book created successfully",
 *         @OA\JsonContent(ref="#/components/schemas/Book")
 *     ),
 * )
 */
public function store(Request $request)
{
    return Book::create($request->all());
}

Get a specific book

• URL: /api/books/{book}
• Method: GET
• Description: Get a specific book

/**
 * @OA\Get(
 *     path="/api/books/{book}",
 *     tags={"Books"},
 *     summary="Get a specific book",
 *     @OA\Parameter(
 *         name="book",
 *         in="path",
 *         description="Book ID",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Returns the specified book",
 *         @OA\JsonContent(ref="#/components/schemas/Book")
 *     ),
 *     @OA\Response(response=404, description="Book not found"),
 * )
 */
public function show(Book $book)
{
    // ...
}

 

Update a book

• URL: /api/books/{book}
• Method: PUT
• Description: Update a book

/**
 * @OA\Put(
 *     path="/api/books/{book}",
 *     tags={"Books"},
 *     summary="Update a book",
 *     @OA\Parameter(
 *         name="book",
 *         in="path",
 *         description="Book ID",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/Book")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Book updated successfully",
 *         @OA\JsonContent(ref="#/components/schemas/Book")
 *     ),
 *     @OA\Response(response=404, description="Book not found"),
 * )
 */
public function update(Request $request, Book $book)
{
    // ...
}

 

Delete a book

• URL: /api/books/{book}
• Method: DELETE
• Description: Delete a book

/**
 * @OA\Delete(
 *     path="/api/books/{book}",
 *     tags={"Books"},
 *     summary="Delete a book",
 *     @OA\Parameter(
 *         name="book",
 *         in="path",
 *         description="Book ID",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(response=200, description="Book deleted successfully"),
 *     @OA\Response(response=404, description="Book not found"),
 * )
 */
public function destroy(Book $book)
{
    // ...
}

 

Get allowed methods

• URL: /api/books
• Method: OPTIONS
• Description: Get allowed methods

/**
 * @OA\Options(
 *     path="/api/books",
 *     tags={"Books"},
 *     summary="Get allowed methods",
 *     @OA\Response(
 *         response=200,
 *         description="Returns the allowed methods",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(type="string")
 *         ),
 *     ),
 * )
 */
public function options()
{
    // ...
}

 

반응형

 

Data Type

/**
 * @OA\Property(
 *     type="integer"
 * )
 */
public $age;

/**
 * @OA\Property(
 *     type="string"
 * )
 */
public $name;

/**
 * @OA\Property(
 *     type="boolean"
 * )
 */
public $isActive;

/**
 * @OA\Property(
 *     type="array",
 *     @OA\Items(type="string")
 * )
 */
public $tags;

/**
 * @OA\Property(
 *     type="object",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="name", type="string")
 * )
 */
public $user;

---

Date Type 정의

/**
 * @OA\Get(
 * ...
 * @OA\Parameter(name="name[]", in="query", required=false, @OA\Schema(type="array", maxLength=2, @OA\Items(type="string", format="date"))),
 */
  public function functionName(Type abc)
  {
        // ...
  }
)

---