chore(docs): Generated API Reference (#3326)

Co-authored-by: shahednasser <shahednasser@users.noreply.github.com>
2023-02-23 17:49:38 +02:00
parent 8d453d35a9
commit 89ed4cd2b1
6 changed files with 1573 additions and 82 deletions
--- a/docs/api/admin/openapi.yaml
+++ b/docs/api/admin/openapi.yaml
@@ -25,18 +25,67 @@ info:
    entity's relations and return them in the response.


-    For example, when you list customers you can also retrieve their groups by
-    passing to the `expand` query parameter the value `groups`.
+    Please note that the relations you pass to `expand` replace any relations
+    that are expanded by default in the request.
+
+
+    ### Expanding One Relation
+
+
+    For example, when you retrieve products, you can retrieve their collection
+    by passing to the `expand` query parameter the value `collection`:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?expand=collection" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Expanding Multiple Relations


    You can expand more than one relation by separating the relations in the
-    `expand` query parameter with a comma. For example, to retrieve both the
-    orders and the groups of a customer, pass to the `expand` query parameter
-    the value `groups,orders`.
+    `expand` query parameter with a comma.


-    Please note that the parameters you pass to `expand` replace any relations
-    that are expanded by default.
+    For example, to retrieve both the variants and the collection of products,
+    pass to the `expand` query parameter the value `variants,collection`:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?expand=variants,collection" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Prevent Expanding Relations
+
+
+    Some requests expand relations by default. You can prevent that by passing
+    an empty expand value to retrieve an entity without any extra relations.
+
+
+    For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?expand" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    This would retrieve each product with only its properties, without any
+    relations like `collection`.


    ## Selecting Fields
@@ -47,17 +96,262 @@ info:
    fields in the entity should be returned in the response.


+    Please note that if you pass a `fields` query parameter, only the fields you
+    pass in the value along with the `id` of the entity will be returned in the
+    response.
+
+
+    Also, the `fields` query parameter does not affect the expanded relations.
+    You'll have to use the `expand` parameter instead.
+
+
+    ### Selecting One Field
+
+
+    For example, when you retrieve a list of products, you can retrieve only the
+    titles of the products by passing `title` as a value to the `fields` query
+    parameter:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?fields=title" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    As mentioned above, the expanded relations such as `variants` will still be
+    returned as they're not affected by the `fields` parameter.
+
+
+    You can ensure that only the `title` field is returned by passing an empty
+    value to the `expand` query parameter. For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?fields=title&expand" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Selecting Multiple Fields
+
+
    You can pass more than one field by seperating the field names in the
    `fields` query parameter with a comma.


-    Only the fields you pass to `field` will be retrieved and returned in the
-    response. Any fields that are returned by default will not be returned in
-    this case. This does not affect relations.
+    For example, to select the `title` and `handle` of products:


-    For example, to only select the `title` and `description` fields of a
-    product, pass to the `fields` query parameter the value `title,description`.
+    ```bash
+
+    curl "http://localhost:9000/admin/products?fields=title,handle" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Retrieve Only the ID
+
+
+    You can pass an empty `fields` query parameter to return only the ID of an
+    entity. For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?fields" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    You can also pair with an empty `expand` query parameter to ensure that the
+    relations aren't retrieved as well. For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?fields&expand" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ## Query Parameter Types
+
+
+    This section covers how to pass some common data types as query parameters.
+    This is useful if you're sending requests to the API endpoints and not using
+    our JS Client. For example, when using cURL or Postman.
+
+
+    ### Strings
+
+
+    You can pass a string value in the form of `<parameter_name>=<value>`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?title=Shirt" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    If the string has any characters other than letters and numbers, you must
+    encode them.
+
+
+    For example, if the string has spaces, you can encode the space with `+` or
+    `%20`:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    You can use tools like [this one](https://www.urlencoder.org/) to learn how
+    a value can be encoded.
+
+
+    ### Integers
+
+
+    You can pass an integer value in the form of `<parameter_name>=<value>`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?offset=1" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Boolean
+
+
+    You can pass a boolean value in the form of `<parameter_name>=<value>`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?is_giftcard=true" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Date and DateTime
+
+
+    You can pass a date value in the form `<parameter_name>=<value>`. The date
+    must be in the format `YYYY-MM-DD`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please
+    note that the `T` and `Z` here are fixed.
+
+
+    For example:
+
+
+    ```bash
+
+    curl -g
+    "http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    ### Array
+
+
+    Each array value must be passed as a separate query parameter in the form
+    `<parameter_name>[]=<value>`. You can also specify the index of each
+    parameter in the brackets `<parameter_name>[0]=<value>`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl -g
+    "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"
+    \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
+    Note that the `-g` parameter passed to `curl` disables errors being thrown
+    for using the brackets. Read more
+    [here](https://curl.se/docs/manpage.html#-g).
+
+
+    ### Object
+
+
+    Object parameters must be passed as separate query parameters in the form
+    `<parameter_name>[<key>]=<value>`.
+
+
+    For example:
+
+
+    ```bash
+
+    curl -g
+    "http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"
+    \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```


    ## Pagination
@@ -80,16 +374,30 @@ info:
    offset should be 50, and so on.


+    For example, to limit the number of products returned in the List Products
+    endpoint:
+
+
+    ```bash
+
+    curl "http://localhost:9000/admin/products?limit=5" \
+
+    -H 'Authorization: Bearer {api_token}'
+
+    ```
+
+
    ### Response Fields


-    In listing fields, aside from the entities retrieved, there are three
-    pagination-related fields returned: `count`, `limit`, and `offset`.
+    In the response of listing endpoints, aside from the entities retrieved,
+    there are three pagination-related fields returned: `count`, `limit`, and
+    `offset`.


-    Similarly to the query parameters, `limit` is the maximum number of items
-    that can be returned in the response, and `field` is the number of items
-    that were skipped before the entities in the result.
+    Similar to the query parameters, `limit` is the maximum number of items that
+    can be returned in the response, and `field` is the number of items that
+    were skipped before the entities in the result.


    `count` is the total number of available items of this entity. It can be