Generating Docs with Swagger UI and Redoc

Swagger UI renders an OpenAPI document as an interactive HTML page where developers can read descriptions, view schemas, and execute live requests against the API. Redoc is an alternative renderer that produces cleaner three-panel documentation suited for public API portals. In Laravel, the l5-swagger package auto-generates the OpenAPI document from PHP docblock annotations and exposes Swagger UI at /api/documentation. Alternatively, writing the OpenAPI document by hand in a YAML file and serving it is more reliable for complex APIs where annotations become unwieldy.

Example

# Install in Laravel
# composer require darkaonline/l5-swagger
# php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

# config/l5-swagger.php key settings:
# 'documentations' => [
#   'default' => [
#     'api' => [ 'title' => 'My API' ],
#     'routes' => [ 'api' => 'api/documentation' ],
#   ]
# ]

# Annotation-based approach (in Controller)
/**
 * @OA\Get(
 *   path="/products",
 *   summary="List products",
 *   tags={"Products"},
 *   security={{ "bearerAuth":{} }},
 *   @OA\Parameter(name="status", in="query", @OA\Schema(type="string")),
 *   @OA\Response(
 *     response=200, description="OK",
 *     @OA\JsonContent(ref="#/components/schemas/ProductList")
 *   ),
 *   @OA\Response(response=401, description="Unauthenticated")
 * )
 */
public function index(Request $request): JsonResponse { ... }

# Generate the spec:
# php artisan l5-swagger:generate
# Visit: http://localhost:8000/api/documentation

# Serve static Swagger UI from a YAML file (any stack):
# docker run -p 8080:8080 \
#   -e SWAGGER_JSON=/spec/openapi.yaml \
#   -v $(pwd)/docs:/spec \
#   swaggerapi/swagger-ui
# Visit: http://localhost:8080

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned