Skip to content

API documentation improvements #395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

API documentation improvements #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5abef87
Improve API documentation
serge-webspark May 15, 2025
d0de562
Improve doc types
serge-webspark May 15, 2025
37f0319
Add Cart description
serge-webspark May 15, 2025
18621f4
Improve wishlist
serge-webspark May 16, 2025
f5a4b86
Fix attribute options
serge-webspark May 16, 2025
e0e6eb3
Fix CS
serge-webspark May 16, 2025
664015c
Add type options
serge-webspark May 17, 2025
1633f8b
Add actual fields for the product image resource
serge-webspark May 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/Docs/Shop/Controllers/Catalog/CategoryController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,8 @@ public function get()
*
* @OA\Property(
* property="data",
* type="object",
* ref="#/components/schemas/Category"
* type="array",
* * @OA\Items(ref="#/components/schemas/Category")
* )
* )
* ),
Expand Down
2 changes: 1 addition & 1 deletion src/Docs/Shop/Controllers/Catalog/ProductController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ public function configurableConfig()
* @OA\Property(
* property="attachments[]",
* type="array",
* @OA\Items(type="file"),
* @OA\Items(type="string", format="binary"),
* description="Array of attachment files (images or videos)"
* ),
* required={"comment", "rating", "title"}
Expand Down
9 changes: 4 additions & 5 deletions src/Docs/Shop/Controllers/Core/CountryController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,11 +197,10 @@ public function get()
* description="Successful operation",
*
* @OA\JsonContent(
*
* @OA\Property(
* property="data",
* type="object",
* ref="#/components/schemas/CountryState"
* type="array",
* @OA\Items(ref="#/components/schemas/CountryState")
* )
* )
* ),
Expand Down Expand Up @@ -232,8 +231,8 @@ public function states()
*
* @OA\Property(
* property="data",
* type="object",
* ref="#/components/schemas/CountryState"
* type="array",
* @OA\Items(ref="#/components/schemas/CountryState")
* )
* )
* ),
Expand Down
83 changes: 33 additions & 50 deletions src/Docs/Shop/Controllers/Customer/CheckoutController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ class CheckoutController
*
* @OA\Property(
* property="billing",
* type="array",
* type="object",
* description="",
* example={
* "id": 14,
Expand All @@ -36,32 +36,26 @@ class CheckoutController
* "city": "Marrero",
* "state": "LA",
* "country": "US",
* "postcode": 70072,
* "postcode": "70072",
* "phone": 9871234560
* },
*
* @OA\Items(
*
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="address", type="array", @OA\Items(
* @OA\Property(type="string")
* )),
* @OA\Property(property="save_as_address", type="boolean"),
* @OA\Property(property="use_for_shipping", type="boolean"),
* @OA\Property(property="first_name", type="string"),
* @OA\Property(property="last_name", type="string"),
* @OA\Property(property="email", type="string"),
* @OA\Property(property="company_name", type="string"),
* @OA\Property(property="city", type="string"),
* @OA\Property(property="state", type="string"),
* @OA\Property(property="country", type="string"),
* @OA\Property(property="postcode", type="integer"),
* @OA\Property(property="phone", type="integer")
* )
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="address", type="array", @OA\Items(@OA\Property(type="string"))),
* @OA\Property(property="save_as_address", type="boolean"),
* @OA\Property(property="use_for_shipping", type="boolean"),
* @OA\Property(property="first_name", type="string"),
* @OA\Property(property="last_name", type="string"),
* @OA\Property(property="email", type="string"),
* @OA\Property(property="company_name", type="string"),
* @OA\Property(property="city", type="string"),
* @OA\Property(property="state", type="string"),
* @OA\Property(property="country", type="string"),
* @OA\Property(property="postcode", type="string"),
* @OA\Property(property="phone", type="integer")
* ),
* @OA\Property(
* property="shipping",
* type="array",
* type="object",
* description="",
* example={
* "id": null,
Expand All @@ -74,27 +68,23 @@ class CheckoutController
* "city": "Mansfield",
* "state": "OH",
* "country": "US",
* "postcode": 44907,
* "postcode": "44907",
* "phone": 987654321
* },
*
* @OA\Items(
*
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="address", type="array", @OA\Items(
* @OA\Property(type="string")
* )),
* @OA\Property(property="save_as_address", type="boolean"),
* @OA\Property(property="first_name", type="string"),
* @OA\Property(property="last_name", type="string"),
* @OA\Property(property="email", type="string"),
* @OA\Property(property="company_name", type="string"),
* @OA\Property(property="city", type="string"),
* @OA\Property(property="state", type="string"),
* @OA\Property(property="country", type="string"),
* @OA\Property(property="postcode", type="integer"),
* @OA\Property(property="phone", type="integer")
* )
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="address", type="array", @OA\Items(
* @OA\Property(type="string")
* )),
* @OA\Property(property="save_as_address", type="boolean"),
* @OA\Property(property="first_name", type="string"),
* @OA\Property(property="last_name", type="string"),
* @OA\Property(property="email", type="string"),
* @OA\Property(property="company_name", type="string"),
* @OA\Property(property="city", type="string"),
* @OA\Property(property="state", type="string"),
* @OA\Property(property="country", type="string"),
* @OA\Property(property="postcode", type="string"),
* @OA\Property(property="phone", type="integer")
* ),
* required={"billing"}
* )
Expand Down Expand Up @@ -246,15 +236,8 @@ public function saveShipping()
*
* @OA\Property(
* property="payment",
* type="array",
* example={
* "method": "cashondelivery"
* },
*
* @OA\Items(
*
* @OA\Property(property="method", type="string")
* )
* type="object",
* @OA\Property(property="method", type="string", example="cashondelivery"),
* ),
* required={"payment"}
* )
Expand Down
34 changes: 28 additions & 6 deletions src/Docs/Shop/Controllers/Customer/WishlistController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,23 @@ class WishlistController
*
* @OA\Property(
* property="data",
* type="object",
* ref="#/components/schemas/Wishlist"
* type="array",
* @OA\Items(
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="product", type="object", ref="#/components/schemas/Product"),
* @OA\Property(
* property="created_at",
* example="2020-01-27 17:50:45",
* format="datetime",
* type="string"
* ),
* @OA\Property(
* property="updated_at",
* example="2020-01-27 17:50:45",
* format="datetime",
* type="string"
* )
* )
* )
* )
* ),
Expand Down Expand Up @@ -67,14 +82,14 @@ public function get()
* mediaType="application/json",
*
* @OA\Schema(
*
* required={"product_id"},
* @OA\Property(property="product_id", type="integer", example=1),
* @OA\Property(
* property="additional",
* type="array",
* example={
* "selected_configurable_option": 2,
* "quantity": 1,
* "product_id": 1,
* "super_attribute": {
* "attribute_id_1": "attribute_option_id_1",
* "attribute_id_2": "attribute_option_id_2"
Expand All @@ -88,10 +103,8 @@ public function get()
* type="array",
*
* @OA\Items(
*
* @OA\Property(property="selected_configurable_option", type="integer"),
* @OA\Property(property="quantity", type="integer"),
* @OA\Property(property="product_id", type="integer"),
* @OA\Property(
* property="super_attribute",
* type="array",
Expand Down Expand Up @@ -153,6 +166,15 @@ public function store()
* )
* ),
*
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(property="quantity", type="integer", example=1, nullable=true)
* )
* )
* ),
*
* @OA\Response(
* response=200,
* description="Successful operation",
Expand Down
6 changes: 4 additions & 2 deletions src/Docs/Shop/Models/Catalog/Attribute.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,12 @@ class Attribute
/**
* @OA\Property(
* title="Options",
* description="Attribute's options"
* description="Attribute's options",
* type="array",
* @OA\Items(ref="#/components/schemas/AttributeOption")
* )
*
* @var \Webkul\RestApi\Docs\Shop\Models\Catalog\AttributeOption
* @var \Webkul\RestApi\Docs\Shop\Models\Catalog\AttributeOption[]
*/
public $options;

Expand Down
4 changes: 3 additions & 1 deletion src/Docs/Shop/Models/Catalog/AttributeFamily.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,9 @@ class AttributeFamily
/**
* @OA\Property(
* title="Groups",
* description="Attribute's groups"
* description="Attribute's groups",
* type="array",
* @OA\Items(ref="#/components/schemas/AttributeGroup")
* )
*
* @var \Webkul\RestApi\Docs\Shop\Models\Catalog\AttributeGroup
Expand Down
4 changes: 3 additions & 1 deletion src/Docs/Shop/Models/Catalog/AttributeGroup.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,9 @@ class AttributeGroup
/**
* @OA\Property(
* title="Attributes",
* description="Attributes"
* description="Attributes",
* type="array",
* @OA\Items(ref="#/components/schemas/Attribute")
* )
*
* @var \Webkul\RestApi\Docs\Shop\Models\Catalog\Attribute
Expand Down
28 changes: 18 additions & 10 deletions src/Docs/Shop/Models/Catalog/Product.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,18 +70,20 @@ class Product
* @OA\Property(
* title="Price",
* description="Product price",
* example=12.20
* example="12.20",
* type="string"
* )
*
* @var float
* @var string
*/
public $price;

/**
* @OA\Property(
* title="Formatted Price",
* description="Product's formatted price",
* example="$12.20"
* example="$12.20",
* type="string"
* )
*
* @var string
Expand Down Expand Up @@ -113,7 +115,9 @@ class Product
/**
* @OA\Property(
* title="Images",
* description="Product's images"
* description="Product's images",
* type="array",
* @OA\Items(ref="#/components/schemas/ProductImage")
* )
*
* @var \Webkul\RestApi\Docs\Shop\Models\Catalog\ProductImage
Expand Down Expand Up @@ -287,18 +291,20 @@ class Product
* @OA\Property(
* title="Special Price",
* description="Product's special price, Only use if special_price is applied to product",
* example=8.00
* example="8.00",
* type="string"
* )
*
* @var float
* @var string
*/
public $special_price;

/**
* @OA\Property(
* title="Formatted Special Price",
* description="Product's formatted special price, Only use if special_price is applied to product",
* example="$8.00"
* example="$8.00",
* type="string"
* )
*
* @var string
Expand All @@ -309,18 +315,20 @@ class Product
* @OA\Property(
* title="Regular Price",
* description="Product's regular price",
* example=12.20
* example="12.20",
* type="string"
* )
*
* @var float
* @var string
*/
public $regular_price;

/**
* @OA\Property(
* title="Formatted Regular Price",
* description="Product's formatted regular price",
* example="$12.20"
* example="$12.20",
* type="string"
* )
*
* @var string
Expand Down
6 changes: 3 additions & 3 deletions src/Docs/Shop/Models/Catalog/ProductConfigurableConfig.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,13 +198,13 @@ class ProductConfigurableConfig
* @OA\Property(
* property="regular_price",
* type="object",
* @OA\Property(property="price", type="integer", example=60.00),
* @OA\Property(property="price", type="string", example="60.00"),
* @OA\Property(property="formated_price", type="string", example="$60.00")
* ),
* @OA\Property(
* property="final_price",
* type="object",
* @OA\Property(property="price", type="integer", example=60.00),
* @OA\Property(property="price", type="string", example="60.00"),
* @OA\Property(property="formated_price", type="string", example="$60.00")
* )
* )
Expand Down Expand Up @@ -301,7 +301,7 @@ class ProductConfigurableConfig
* "price": 30
* },
* @OA\Property(property="formated_price", type="string", example="$30.00"),
* @OA\Property(property="price", type="float", example=30.00)
* @OA\Property(property="price", type="string", example="30.00")
* )
*
* @var object
Expand Down
Loading