Fix swagger's operationId for all API endpoints

2024-11-09 20:52:56 +01:00 · 2017-03-09 17:22:37 +01:00 · 2017-03-09 17:22:37 +01:00 · d7f3ac8d2c
commit d7f3ac8d2c
parent 419e950448
14 changed files with 113 additions and 56 deletions
--- a/app/Console/Commands/stubs/api-controller.stub
+++ b/app/Console/Commands/stubs/api-controller.stub
@ -23,7 +23,8 @@ class $STUDLY_NAME$ApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/$LOWER_NAME$",
-     *   summary="List of $LOWER_NAME$",
+     *   summary="List $LOWER_NAME$",
+     *   operationId="list$STUDLY_NAME$s",
     *   tags={"$LOWER_NAME$"},
     *   @SWG\Response(
     *     response=200,
@ -47,6 +48,7 @@ class $STUDLY_NAME$ApiController extends BaseAPIController
     * @SWG\Get(
     *   path="/$LOWER_NAME$/{$LOWER_NAME$_id}",
     *   summary="Individual $STUDLY_NAME$",
+     *   operationId="get$STUDLY_NAME$",
     *   tags={"$LOWER_NAME$"},
     *   @SWG\Parameter(
     *     in="path",
@ -76,8 +78,9 @@ class $STUDLY_NAME$ApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/$LOWER_NAME$",
-     *   tags={"$LOWER_NAME$"},
     *   summary="Create a $LOWER_NAME$",
+     *   operationId="create$STUDLY_NAME$",
+     *   tags={"$LOWER_NAME$"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="$LOWER_NAME$",
@ -104,8 +107,9 @@ class $STUDLY_NAME$ApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/$LOWER_NAME$/{$LOWER_NAME$_id}",
-     *   tags={"$LOWER_NAME$"},
     *   summary="Update a $LOWER_NAME$",
+     *   operationId="update$STUDLY_NAME$",
+     *   tags={"$LOWER_NAME$"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="$LOWER_NAME$_id",
@ -143,8 +147,9 @@ class $STUDLY_NAME$ApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/$LOWER_NAME$/{$LOWER_NAME$_id}",
-     *   tags={"$LOWER_NAME$"},
     *   summary="Delete a $LOWER_NAME$",
+     *   operationId="delete$STUDLY_NAME$",
+     *   tags={"$LOWER_NAME$"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="$LOWER_NAME$_id",
--- a/app/Http/Controllers/BaseAPIController.php
+++ b/app/Http/Controllers/BaseAPIController.php
@ -20,6 +20,7 @@ use Utils;
 *     schemes={"http","https"},
 *     host="ninja.dev",
 *     basePath="/api/v1",
+ *     produces={"application/json"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="Invoice Ninja API",
--- a/app/Http/Controllers/ClientApiController.php
+++ b/app/Http/Controllers/ClientApiController.php
@ -26,7 +26,8 @@ class ClientApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/clients",
-     *   summary="List of clients",
+     *   summary="List clients",
+     *   operationId="listClients",
     *   tags={"client"},
     *   @SWG\Response(
     *     response=200,
@ -58,7 +59,8 @@ class ClientApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/clients/{client_id}",
-     *   summary="Individual Client",
+     *   summary="Retrieve a client",
+     *   operationId="getClient",
     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="path",
@ -85,8 +87,9 @@ class ClientApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/clients",
-     *   tags={"client"},
     *   summary="Create a client",
+     *   operationId="createClient",
+     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="client",
@ -113,8 +116,9 @@ class ClientApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/clients/{client_id}",
-     *   tags={"client"},
     *   summary="Update a client",
+     *   operationId="updateClient",
+     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="client_id",
@ -157,8 +161,9 @@ class ClientApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/clients/{client_id}",
-     *   tags={"client"},
     *   summary="Delete a client",
+     *   operationId="deleteClient",
+     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="client_id",
--- a/app/Http/Controllers/DocumentAPIController.php
+++ b/app/Http/Controllers/DocumentAPIController.php
@ -38,7 +38,8 @@ class DocumentAPIController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/documents",
-     *   summary="List of document",
+     *   summary="List document",
+     *   operationId="listDocuments",
     *   tags={"document"},
     *   @SWG\Response(
     *     response=200,
@ -65,8 +66,9 @@ class DocumentAPIController extends BaseAPIController
     *
     * @SWG\Get(
     *   path="/documents/{document_id}",
-     *   tags={"document"},
     *   summary="Download a document",
+     *   operationId="getDocument",
+     *   tags={"document"},
     *   produces={"application/octet-stream"},
     *   @SWG\Parameter(
     *     in="path",
@ -99,8 +101,9 @@ class DocumentAPIController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/documents",
-     *   tags={"document"},
     *   summary="Create a document",
+     *   operationId="createDocument",
+     *   tags={"document"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="document",
@ -127,8 +130,9 @@ class DocumentAPIController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/documents/{document_id}",
+     *   summary="Delete a document",
+     *   operationId="deleteDocument",
     *   tags={"document"},
-     *   summary="Delete a client",
     *   @SWG\Parameter(
     *     in="path",
     *     name="document_id",
--- a/app/Http/Controllers/ExpenseApiController.php
+++ b/app/Http/Controllers/ExpenseApiController.php
@ -28,7 +28,8 @@ class ExpenseApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/expenses",
-     *   summary="List of expenses",
+     *   summary="List expenses",
+     *   operationId="listExpenses",
     *   tags={"expense"},
     *   @SWG\Response(
     *     response=200,
@ -54,8 +55,9 @@ class ExpenseApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/expenses/{expense_id}",
-     *   tags={"expense"},
     *   summary="Retrieve an expense",
+     *   operationId="getExpense",
+     *   tags={"expense"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="expense_id",
@ -81,8 +83,9 @@ class ExpenseApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/expenses",
-     *   tags={"expense"},
     *   summary="Create an expense",
+     *   operationId="createExpense",
+     *   tags={"expense"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="expense",
@ -113,8 +116,9 @@ class ExpenseApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/expenses/{expense_id}",
-     *   tags={"expense"},
     *   summary="Update an expense",
+     *   operationId="updateExpense",
+     *   tags={"expense"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="expense_id",
@ -155,8 +159,9 @@ class ExpenseApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/expenses/{expense_id}",
-     *   tags={"expense"},
     *   summary="Delete an expense",
+     *   operationId="deleteExpense",
+     *   tags={"expense"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="expense_id",
--- a/app/Http/Controllers/ExpenseCategoryApiController.php
+++ b/app/Http/Controllers/ExpenseCategoryApiController.php
@ -27,7 +27,8 @@ class ExpenseCategoryApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/expense_categories",
-     *   summary="List of expense categories",
+     *   summary="List expense categories",
+     *   operationId="listExpenseCategories",
     *   tags={"expense_category"},
     *   @SWG\Response(
     *     response=200,
@ -52,7 +53,8 @@ class ExpenseCategoryApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/expense_categories/{expense_category_id}",
-     *   summary="Individual Expense Category",
+     *   summary="Retrieve an Expense Category",
+     *   operationId="getExpenseCategory",
     *   tags={"expense_category"},
     *   @SWG\Parameter(
     *     in="path",
@ -79,8 +81,9 @@ class ExpenseCategoryApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/expense_categories",
-     *   tags={"expense_category"},
     *   summary="Create an expense category",
+     *   operationId="createExpenseCategory",
+     *   tags={"expense_category"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="expense_category",
@ -107,8 +110,9 @@ class ExpenseCategoryApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/expense_categories/{expense_category_id}",
-     *   tags={"expense_category"},
     *   summary="Update an expense category",
+     *   operationId="updateExpenseCategory",
+     *   tags={"expense_category"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="expense_category_id",
@ -141,8 +145,9 @@ class ExpenseCategoryApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/expense_categories/{expense_category_id}",
-     *   tags={"expense_category"},
     *   summary="Delete an expense category",
+     *   operationId="deleteExpenseCategory",
+     *   tags={"expense_category"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="expense_category_id",
--- a/app/Http/Controllers/InvoiceApiController.php
+++ b/app/Http/Controllers/InvoiceApiController.php
@ -42,7 +42,8 @@ class InvoiceApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/invoices",
-     *   summary="List of invoices",
+     *   summary="List invoices",
+     *   operationId="listInvoices",
     *   tags={"invoice"},
     *   @SWG\Response(
     *     response=200,
@ -68,7 +69,7 @@ class InvoiceApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/invoices/{invoice_id}",
-     *   summary="Individual Invoice",
+     *   summary="Retrieve an Invoice",
     *   tags={"invoice"},
     *   @SWG\Parameter(
     *     in="path",
@ -95,8 +96,8 @@ class InvoiceApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/invoices",
-     *   tags={"invoice"},
     *   summary="Create an invoice",
+     *   tags={"invoice"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="invoice",
@ -314,8 +315,8 @@ class InvoiceApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/invoices/{invoice_id}",
-     *   tags={"invoice"},
     *   summary="Update an invoice",
+     *   tags={"invoice"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="invoice_id",
@ -365,8 +366,8 @@ class InvoiceApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/invoices/{invoice_id}",
-     *   tags={"invoice"},
     *   summary="Delete an invoice",
+     *   tags={"invoice"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="invoice_id",
--- a/app/Http/Controllers/PaymentApiController.php
+++ b/app/Http/Controllers/PaymentApiController.php
@ -29,8 +29,9 @@ class PaymentApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/payments",
+     *   summary="List payments",
+     *   operationId="listPayments",
     *   tags={"payment"},
-     *   summary="List of payments",
     *   @SWG\Response(
     *     response=200,
     *     description="A list of payments",
@ -55,8 +56,9 @@ class PaymentApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/payments/{payment_id}",
-     *   tags={"payment"},
     *   summary="Retrieve a payment",
+     *   operationId="getPayment",
+     *   tags={"payment"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="payment_id",
@ -83,6 +85,7 @@ class PaymentApiController extends BaseAPIController
     * @SWG\Post(
     *   path="/payments",
     *   summary="Create a payment",
+     *   operationId="createPayment",
     *   tags={"payment"},
     *   @SWG\Parameter(
     *     in="body",
@ -118,6 +121,7 @@ class PaymentApiController extends BaseAPIController
     * @SWG\Put(
     *   path="/payments/{payment_id}",
     *   summary="Update a payment",
+     *   operationId="updatePayment",
     *   tags={"payment"},
     *   @SWG\Parameter(
     *     in="path",
@ -160,6 +164,7 @@ class PaymentApiController extends BaseAPIController
     * @SWG\Delete(
     *   path="/payments/{payment_id}",
     *   summary="Delete a payment",
+     *   operationId="deletePayment",
     *   tags={"payment"},
     *   @SWG\Parameter(
     *     in="path",
--- a/app/Http/Controllers/ProductApiController.php
+++ b/app/Http/Controllers/ProductApiController.php
@ -38,7 +38,8 @@ class ProductApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/products",
-     *   summary="List of products",
+     *   summary="List products",
+     *   operationId="listProducts",
     *   tags={"product"},
     *   @SWG\Response(
     *     response=200,
@ -63,8 +64,9 @@ class ProductApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/products/{product_id}",
-     *   tags={"product"},
     *   summary="Retrieve a product",
+     *   operationId="getProduct",
+     *   tags={"product"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="product_id",
@ -90,8 +92,9 @@ class ProductApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/products",
-     *   tags={"product"},
     *   summary="Create a product",
+     *   operationId="createProduct",
+     *   tags={"product"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="body",
@ -118,8 +121,9 @@ class ProductApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/products/{product_id}",
-     *   tags={"product"},
     *   summary="Update a product",
+     *   operationId="updateProduct",
+     *   tags={"product"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="product_id",
@ -160,8 +164,9 @@ class ProductApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/products/{product_id}",
-     *   tags={"product"},
     *   summary="Delete a product",
+     *   operationId="deleteProduct",
+     *   tags={"product"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="product_id",
--- a/app/Http/Controllers/QuoteApiController.php
+++ b/app/Http/Controllers/QuoteApiController.php
@ -22,8 +22,9 @@ class QuoteApiController extends InvoiceAPIController
    /**
     * @SWG\Get(
     *   path="/quotes",
+     *   summary="List quotes",
+     *   operationId="listQuotes",
     *   tags={"quote"},
-     *   summary="List of quotes",
     *   @SWG\Response(
     *     response=200,
     *     description="A list of quotes",
--- a/app/Http/Controllers/TaskApiController.php
+++ b/app/Http/Controllers/TaskApiController.php
@ -27,8 +27,9 @@ class TaskApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/tasks",
+     *   summary="List tasks",
+     *   operationId="listTasks",
     *   tags={"task"},
-     *   summary="List of tasks",
     *   @SWG\Response(
     *     response=200,
     *     description="A list of tasks",
@ -53,7 +54,8 @@ class TaskApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/tasks/{task_id}",
-     *   summary="Individual task",
+     *   summary="Retrieve a task",
+     *   operationId="getTask",
     *   tags={"task"},
     *   @SWG\Parameter(
     *     in="path",
@ -80,8 +82,9 @@ class TaskApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/tasks",
-     *   tags={"task"},
     *   summary="Create a task",
+     *   operationId="createTask",
+     *   tags={"task"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="task",
@ -119,8 +122,9 @@ class TaskApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/tasks/{task_id}",
-     *   tags={"task"},
     *   summary="Update a task",
+     *   operationId="updateTask",
+     *   tags={"task"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="task_id",
@ -155,8 +159,9 @@ class TaskApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/tasks/{task_id}",
-     *   tags={"task"},
     *   summary="Delete a task",
+     *   operationId="deleteTask",
+     *   tags={"task"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="task_id",
--- a/app/Http/Controllers/TaxRateApiController.php
+++ b/app/Http/Controllers/TaxRateApiController.php
@ -35,7 +35,8 @@ class TaxRateApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/tax_rates",
-     *   summary="List of tax rates",
+     *   summary="List tax rates",
+     *   operationId="listTaxRates",
     *   tags={"tax_rate"},
     *   @SWG\Response(
     *     response=200,
@ -60,8 +61,9 @@ class TaxRateApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/tax_rates/{tax_rate_id}",
-     *   tags={"tax_rate"},
     *   summary="Retrieve a tax rate",
+     *   operationId="getTaxRate",
+     *   tags={"tax_rate"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="tax_rate_id",
@ -87,8 +89,9 @@ class TaxRateApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/tax_rates",
-     *   tags={"tax_rate"},
     *   summary="Create a tax rate",
+     *   operationId="createTaxRate",
+     *   tags={"tax_rate"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="tax_rate",
@ -115,8 +118,9 @@ class TaxRateApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/tax_rates/{tax_rate_id}",
-     *   tags={"tax_rate"},
     *   summary="Update a tax rate",
+     *   operationId="updateTaxRate",
+     *   tags={"tax_rate"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="tax_rate_id",
@ -157,8 +161,9 @@ class TaxRateApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/tax_rates/{tax_rate_id}",
-     *   tags={"tax_rate"},
     *   summary="Delete a tax rate",
+     *   operationId="deleteTaxRate",
+     *   tags={"tax_rate"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="tax_rate_id",
--- a/app/Http/Controllers/UserApiController.php
+++ b/app/Http/Controllers/UserApiController.php
@ -29,7 +29,8 @@ class UserApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/users",
-     *   summary="List of users",
+     *   summary="List users",
+     *   operationId="listUsers",
     *   tags={"user"},
     *   @SWG\Response(
     *     response=200,
@ -54,7 +55,8 @@ class UserApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/users/{user_id}",
-     *   summary="Individual user",
+     *   summary="Retrieve a user",
+     *   operationId="getUser",
     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="path",
@ -81,8 +83,9 @@ class UserApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/users",
-     *   tags={"user"},
     *   summary="Create a user",
+     *   operationId="createUser",
+     *   tags={"user"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="user",
@ -107,8 +110,9 @@ class UserApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/users/{user_id}",
-     *   tags={"user"},
     *   summary="Update a user",
+     *   operationId="updateUser",
+     *   tags={"user"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="user_id",
@ -162,8 +166,9 @@ class UserApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/users/{user_id}",
-     *   tags={"user"},
     *   summary="Delete a user",
+     *   operationId="deleteUser",
+     *   tags={"user"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="user_id",
--- a/app/Http/Controllers/VendorApiController.php
+++ b/app/Http/Controllers/VendorApiController.php
@ -34,7 +34,8 @@ class VendorApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/vendors",
-     *   summary="List of vendors",
+     *   summary="List vendors",
+     *   operationId="listVendors",
     *   tags={"vendor"},
     *   @SWG\Response(
     *     response=200,
@ -59,7 +60,8 @@ class VendorApiController extends BaseAPIController
    /**
     * @SWG\Get(
     *   path="/vendors/{vendor_id}",
-     *   summary="Individual vendor",
+     *   summary="Retrieve a vendor",
+     *   operationId="getVendor",
     *   tags={"client"},
     *   @SWG\Parameter(
     *     in="path",
@ -86,8 +88,9 @@ class VendorApiController extends BaseAPIController
    /**
     * @SWG\Post(
     *   path="/vendors",
-     *   tags={"vendor"},
     *   summary="Create a vendor",
+     *   operationId="createVendor",
+     *   tags={"vendor"},
     *   @SWG\Parameter(
     *     in="body",
     *     name="vendor",
@ -118,8 +121,9 @@ class VendorApiController extends BaseAPIController
    /**
     * @SWG\Put(
     *   path="/vendors/{vendor_id}",
-     *   tags={"vendor"},
     *   summary="Update a vendor",
+     *   operationId="updateVendor",
+     *   tags={"vendor"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="vendor_id",
@ -162,8 +166,9 @@ class VendorApiController extends BaseAPIController
    /**
     * @SWG\Delete(
     *   path="/vendors/{vendor_id}",
-     *   tags={"vendor"},
     *   summary="Delete a vendor",
+     *   operationId="deleteVendor",
+     *   tags={"vendor"},
     *   @SWG\Parameter(
     *     in="path",
     *     name="vendor_id",