Swagger API Documentation

Swagger is a powerful tool for documenting APIs. It provides a user-friendly interface for developers to interact with the API endpoints and understand the request and response structures. This page provides a detailed guide on how to set up Swagger in your PHP project and generate API documentation.

With Swagger, you can easily create and maintain accurate documentation for your APIs. It allows you to define the structure of your API endpoints, including the request and response schemas, authentication requirements, and available parameters. Swagger also provides a built-in testing interface, allowing developers to make API requests directly from the documentation page.

By using Swagger, you can improve the developer experience by providing clear and concise documentation. This helps new developers understand how to use your API and reduces the time spent on support and troubleshooting. Additionally, Swagger documentation can be automatically generated from your code, ensuring that it stays up-to-date as your API evolves.

To get started with Swagger in your PHP project, you'll need to install the Swagger PHP library and configure it to generate documentation based on your code annotations. Once set up, you can access the Swagger documentation page and explore your API endpoints, test them, and view the request and response examples.

Remember to keep your Swagger documentation up-to-date as you make changes to your API. This will ensure that developers always have access to accurate and relevant information about your API endpoints.

Advanced Usage and Customization

1. npm run create-swagger-docs - This command can also be used to generate docs for specific models. You can pass one or more model names from your schema.prisma file:

   npm run create-swagger-docs Order

   npm run create-swagger-docs Order User Client

2. Upon running the command, you will be prompted to answer the following:
   • ✔ Do you want to generate Swagger docs only?
   • ✔ Do you want to generate endpoints?
   • ✔ Do you want to generate PHP classes?
   You can answer true or false to each.
3. The generated Swagger Docs will be placed in:

   src/app/swagger-docs/apis/

   A Swagger JSON file named pphp-swagger.json will be created or updated in this directory.
4. You can customize generation behavior using the configuration file:

   settings/prisma-schema-config.json

   Example:

   {
     "swaggerDocsDir": "src/app/swagger-docs/apis",
     "skipDefaultName": ["autoincrement", "cuid", "uuid", "now"],
     "skipByPropertyValue": {
       "isUpdatedAt": true
     },
     "skipFields": [],
     "generateSwaggerDocsOnly": false,
     "generateEndpoints": true,
     "generatePhpClasses": true
   }

5. 📚 Useful Resources:
   • 🌐 Official Swagger Documentation
   • 💻 Swagger UI (GitHub)
   • 🧾 Swagger JSDoc (GitHub)