Improved Swagger annotations

app/Http/Controllers/DocumentAPIController.php

@@ -33,7 +33,20 @@ class DocumentAPIController extends BaseAPIController
     }
 
     /**
-     * @return \Illuminate\Http\Response
+     * @SWG\Get(
+     *   path="/documents",
+     *   summary="List of document",
+     *   tags={"document"},
+     *   @SWG\Response(
+     *     response=200,
+     *     description="A list with documents",
+     *      @SWG\Schema(type="array", @SWG\Items(ref="#/definitions/Document"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function index()
     {
@@ -59,13 +72,29 @@ class DocumentAPIController extends BaseAPIController
     }
 
     /**
-     * @param CreateDocumentRequest $request
+     * @SWG\Post(
-     *
+     *   path="/documents",
-     * @return \Illuminate\Http\Response
+     *   tags={"document"},
+     *   summary="Create a document",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/Document")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="New document",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/Document"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function store(CreateDocumentRequest $request)
     {
-        
+
         $document = $this->documentRepo->upload($request->all());
 
         return $this->itemResponse($document);

app/Http/Controllers/ExpenseCategoryApiController.php

@@ -9,7 +9,6 @@ use App\Http\Requests\CreateExpenseCategoryRequest;
 use App\Http\Requests\UpdateExpenseCategoryRequest;
 use App\Ninja\Repositories\ExpenseCategoryRepository;
 
-
 class ExpenseCategoryApiController extends BaseAPIController
 {
     protected $categoryRepo;
@@ -19,23 +18,65 @@ class ExpenseCategoryApiController extends BaseAPIController
     public function __construct(ExpenseCategoryRepository $categoryRepo, ExpenseCategoryService $categoryService)
     {
         parent::__construct();
-        
+
         $this->categoryRepo = $categoryRepo;
         $this->categoryService = $categoryService;
     }
 
+    /**
+     * @SWG\Post(
+     *   path="/expense_categories",
+     *   tags={"expense_category"},
+     *   summary="Create an expense category",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/ExpenseCategory")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="New expense category",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/ExpenseCategory"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
+     */
+    public function store(CreateExpenseCategoryRequest $request)
+    {
+        $category = $this->categoryRepo->save($request->input());
+
+        return $this->itemResponse($category);
+    }
+
+
+    /**
+     * @SWG\Put(
+     *   path="/expense_categories/{expense_category_id}",
+     *   tags={"expense_category"},
+     *   summary="Update an expense category",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/ExpenseCategory")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="Update expense category",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/ExpenseCategory"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
+     */
     public function update(UpdateExpenseCategoryRequest $request)
     {
         $category = $this->categoryRepo->save($request->input(), $request->entity());
 
         return $this->itemResponse($category);
     }
-
-    public function store(CreateExpenseCategoryRequest $request)
-    {
-        $category = $this->categoryRepo->save($request->input());
-
-        return $this->itemResponse($category);
-
-    }
 }

app/Http/Controllers/ProductApiController.php

@@ -33,7 +33,20 @@ class ProductApiController extends BaseAPIController
     }
 
     /**
-     * @return \Illuminate\Http\Response
+     * @SWG\Get(
+     *   path="/products",
+     *   summary="List of products",
+     *   tags={"product"},
+     *   @SWG\Response(
+     *     response=200,
+     *     description="A list with products",
+     *      @SWG\Schema(type="array", @SWG\Items(ref="#/definitions/Product"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function index()
     {
@@ -45,8 +58,25 @@ class ProductApiController extends BaseAPIController
     }
 
     /**
-     * @param CreateProductRequest $request
+     * @SWG\Post(
-     * @return \Illuminate\Http\Response
+     *   path="/products",
+     *   tags={"product"},
+     *   summary="Create a product",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/Product")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="New product",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/Product"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function store(CreateProductRequest $request)
     {
@@ -56,16 +86,32 @@ class ProductApiController extends BaseAPIController
     }
 
     /**
-     * @param UpdateProductRequest $request
+     * @SWG\Put(
-     * @param $publicId
+     *   path="/products/{product_id}",
-     * @return \Illuminate\Http\Response
+     *   tags={"product"},
+     *   summary="Update a product",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/Product")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="Update product",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/Product"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function update(UpdateProductRequest $request, $publicId)
     {
         if ($request->action) {
             return $this->handleAction($request);
         }
-        
+
         $data = $request->input();
         $data['public_id'] = $publicId;
         $product = $this->productRepo->save($data, $request->entity());

app/Http/Controllers/TaxRateApiController.php

@@ -28,6 +28,22 @@ class TaxRateApiController extends BaseAPIController
         $this->taxRateRepo = $taxRateRepo;
     }
 
+    /**
+     * @SWG\Get(
+     *   path="/tax_rates",
+     *   summary="List of tax rates",
+     *   tags={"tax_rate"},
+     *   @SWG\Response(
+     *     response=200,
+     *     description="A list with tax rates",
+     *      @SWG\Schema(type="array", @SWG\Items(ref="#/definitions/TaxRate"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
+     */
     public function index()
     {
         $taxRates = TaxRate::scope()
@@ -37,6 +53,27 @@ class TaxRateApiController extends BaseAPIController
         return $this->listResponse($taxRates);
     }
 
+    /**
+     * @SWG\Post(
+     *   path="/tax_rates",
+     *   tags={"tax_rate"},
+     *   summary="Create a tax rate",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/TaxRate")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="New tax rate",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/TaxRate"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
+     */
     public function store(CreateTaxRateRequest $request)
     {
         $taxRate = $this->taxRateRepo->save($request->input());
@@ -45,16 +82,32 @@ class TaxRateApiController extends BaseAPIController
     }
 
     /**
-     * @param UpdateTaxRateRequest $request
+     * @SWG\Put(
-     * @param $publicId
+     *   path="/tax_rates/{tax_rate_id}",
-     * @return \Illuminate\Http\Response
+     *   tags={"tax_rate"},
+     *   summary="Update a tax rate",
+     *   @SWG\Parameter(
+     *     in="body",
+     *     name="body",
+     *     @SWG\Schema(ref="#/definitions/TaxRate")
+     *   ),
+     *   @SWG\Response(
+     *     response=200,
+     *     description="Update tax rate",
+     *      @SWG\Schema(type="object", @SWG\Items(ref="#/definitions/TaxRate"))
+     *   ),
+     *   @SWG\Response(
+     *     response="default",
+     *     description="an ""unexpected"" error"
+     *   )
+     * )
      */
     public function update(UpdateTaxRateRequest $request, $publicId)
     {
         if ($request->action) {
             return $this->handleAction($request);
         }
-        
+
         $data = $request->input();
         $data['public_id'] = $publicId;
         $taxRate = $this->taxRateRepo->save($data, $request->entity());

app/Ninja/Transformers/DocumentTransformer.php

@@ -3,14 +3,19 @@
 use App\Models\Document;
 
 /**
- * Class DocumentTransformer
+ * @SWG\Definition(definition="Document", @SWG\Xml(name="Document"))
  */
 class DocumentTransformer extends EntityTransformer
 {
     /**
-     * @param Document $document
+    * @SWG\Property(property="id", type="integer", example=1, readOnly=true)
-     * @return array
+    * @SWG\Property(property="name", type="string", example="Test")
-     */
+    * @SWG\Property(property="type", type="string", example="CSV")
+    * @SWG\Property(property="invoice_id", type="integer", example=1)
+    * @SWG\Property(property="updated_at", type="timestamp", example=1451160233, readOnly=true)
+    * @SWG\Property(property="archived_at", type="timestamp", example=1451160233, readOnly=true)
+    */
+
     public function transform(Document $document)
     {
         return array_merge($this->getDefaults($document), [

app/Ninja/Transformers/ExpenseCategoryTransformer.php

@@ -2,9 +2,20 @@
 
 use App\Models\ExpenseCategory;
 
+/**
+ * @SWG\Definition(definition="ExpenseCategory", @SWG\Xml(name="ExpenseCategory"))
+ */
+
 class ExpenseCategoryTransformer extends EntityTransformer
 {
 
+    /**
+    * @SWG\Property(property="id", type="integer", example=1, readOnly=true)
+    * @SWG\Property(property="name", type="string", example="Sample")
+    * @SWG\Property(property="updated_at", type="timestamp", example=1451160233, readOnly=true)
+    * @SWG\Property(property="archived_at", type="timestamp", example=1451160233, readOnly=true)
+    */
+
     public function transform(ExpenseCategory $expenseCategory)
     {
         return array_merge($this->getDefaults($expenseCategory), [
@@ -14,4 +25,4 @@ class ExpenseCategoryTransformer extends EntityTransformer
             'archived_at' => $this->getTimestamp($expenseCategory->deleted_at),
         ]);
     }
-}
+}

app/Ninja/Transformers/ProductTransformer.php

@@ -2,8 +2,23 @@
 
 use App\Models\Product;
 
+/**
+ * @SWG\Definition(definition="Product", @SWG\Xml(name="Product"))
+ */
+
 class ProductTransformer extends EntityTransformer
 {
+    /**
+    * @SWG\Property(property="id", type="integer", example=1, readOnly=true)
+    * @SWG\Property(property="product_key", type="string", example="Item")
+    * @SWG\Property(property="notes", type="string", example="Notes...")
+    * @SWG\Property(property="cost", type="float", example=10.00)
+    * @SWG\Property(property="qty", type="float", example=1)
+    * @SWG\Property(property="default_tax_rate_id", type="integer", example=1)
+    * @SWG\Property(property="updated_at", type="timestamp", example=1451160233, readOnly=true)
+    * @SWG\Property(property="archived_at", type="timestamp", example=1451160233, readOnly=true)
+    */
+
     public function transform(Product $product)
     {
         return array_merge($this->getDefaults($product), [
@@ -17,4 +32,4 @@ class ProductTransformer extends EntityTransformer
             'archived_at' => $this->getTimestamp($product->deleted_at),
         ]);
     }
-}
+}

app/Ninja/Transformers/ProjectTransformer.php

@@ -2,8 +2,21 @@
 
 use App\Models\Project;
 
+/**
+ * @SWG\Definition(definition="Project", @SWG\Xml(name="Project"))
+ */
+
 class ProjectTransformer extends EntityTransformer
 {
+    /**
+    * @SWG\Property(property="id", type="integer", example=1, readOnly=true)
+    * @SWG\Property(property="name", type="string", example="Sample")
+    * @SWG\Property(property="client_id", type="integer", example=1)
+    * @SWG\Property(property="updated_at", type="timestamp", example=1451160233, readOnly=true)
+    * @SWG\Property(property="archived_at", type="timestamp", example=1451160233, readOnly=true)
+    * @SWG\Property(property="is_deleted", type="boolean", example=false, readOnly=true)
+    */
+
     public function transform(Project $project)
     {
         return array_merge($this->getDefaults($project), [

config/swaggervel.php

@@ -45,7 +45,8 @@ return array(
         base_path()."/tests",
         base_path()."/resources/views",
         base_path()."/config",
-        base_path()."/vendor"
+        base_path()."/vendor",
+        base_path()."/app/Console/Commands/stubs"
     ),
 
     /*