Merge pull request #120 from jolicode/better-documentation

Improve the documentation

Author: pyrech

.php_cs

@@ -36,7 +36,7 @@ return PhpCsFixer\Config::create()
     ))
     ->setFinder(PhpCsFixer\Finder::create()
         ->in(__DIR__)
-        ->exclude('doc')
+        ->exclude('docs')
         ->exclude('ci_generated')
     )
 ;

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * Add a new Client to ease iteration over Slack paginated endpoints thanks to `iterateXxxx` methods (where `xxxx` is the endpoint name to iterate over)
 * **Specification override** Add missing `locale` for `objs_conversation` model
+* Improve the documentation
 
 ## 4.1.1 (2021-03-16)
 

README.md

@@ -1,19 +1,20 @@
 # A PHP client for Slack's API
 
-There is a bunch of PHP clients for Slack. But some are not up to date or miss
-features, some only cover a small part of the API and most are simply no longer
-maintained.
+There is a bunch of existing PHP clients for Slack. But some are not up to date
+or miss features, some only cover a small part of the API and most are simply
+no longer maintained.
 
 This SDK is generated automatically with [JanePHP](https://github.com/janephp/janephp)
 from the [official Slack API specs](https://github.com/slackapi/slack-api-specs). 
 
-It provides a **full object oriented interface** for all the endpoints, requests and responses of the Slack Web API.
+It also provides a **full object oriented interface** for all the endpoints,
+requests and responses of the Slack Web API.
 
 ## Installation
 
 This library is built atop of [PSR-7](https://www.php-fig.org/psr/psr-7/) and
 [PSR-18](https://www.php-fig.org/psr/psr-18/). So you will need to install some
-implementations for those interfaces.
+implementations for those standard interfaces.
 
 If no PSR-18 client or PSR-7 message factory is available yet in your project
 or you don't know or don't care which one to use, just install some default:
@@ -28,35 +29,18 @@ You can now install the Slack client:
 composer require jolicode/slack-php-api
 ```
 
-## Usage
-
-First, you need to retrieve a token from Slack. 
-
-Checkout Slack's documentation about [all different kind of tokens](https://api.slack.com/authentication/token-types).
-A good starting point is the [Authentication Basics documentation](https://api.slack.com/authentication/basics).
-
-Then, use the factory that is provided to create the client:
+## Quick start
 
 ```php
 // $client contains all the methods to interact with the API
-$client = JoliCode\Slack\ClientFactory::create($yourToken);
+$client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
 
 $user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
-
-dump($user);
 ```
 
-<p align="center">
-  <img src="doc/images/model-sample.png" alt="Sample user object" />
-<p>
-
-Want more example or documentation? See the [full documentation here](doc/index.md).
-
-## Troubleshoots
+## Documentation
 
-Got some problems using this library? Need a missing feature?
-Do not hesitate to [open an issue](https://github.com/jolicode/slack-php-api/issues)
-and share it with us.
+Want more documentation or examples? See the [full documentation here](https://jolicode.github.io/slack-php-api/).
 
 ## Further documentation
 

doc/index.md

@@ -0,0 +1,42 @@
+# Getting started
+
+## Installation
+
+This library is built atop of [PSR-7](https://www.php-fig.org/psr/psr-7/) and
+[PSR-18](https://www.php-fig.org/psr/psr-18/). So you will need to install some
+implementations for those standard interfaces.
+
+If no PSR-18 client or PSR-7 message factory is available yet in your project
+or you don't know or don't care which one to use, just install some default:
+
+```bash
+composer require symfony/http-client nyholm/psr7
+```
+
+You can now install the Slack client:
+
+```bash
+composer require jolicode/slack-php-api
+```
+
+## Slack token
+
+Before you can use this client, you need to retrieve a token from Slack.
+
+Checkout Slack's documentation about [all different kind of tokens](https://api.slack.com/authentication/token-types).
+A good starting point is the [Authentication Basics documentation](https://api.slack.com/authentication/basics).
+
+## Quick start
+
+```php
+// $client contains all the methods to interact with the API
+$client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
+
+$user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
+```
+
+***
+
+Read more:
+- Next page: [Usage](2-usage.md)
+- Previous page: [Introduction](index.md)

docs/1-get-started.md

@@ -0,0 +1,110 @@
+# Usage
+
+## Basic usage of the client
+
+Use the `ClientFactory` to generate a `Client` configured with your token:
+
+```php
+<?php
+
+use JoliCode\Slack\Api\Client;
+use JoliCode\Slack\ClientFactory;
+
+/** @var Client $client */
+$client = ClientFactory::create($yourSlackToken);
+```
+
+The client contains all the methods to communicate with Slack API. Checkout its
+PHPdoc to know which option you can provide to each method:
+
+```php
+<?php
+//...
+
+$user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
+
+dump($user);
+```
+
+Here is what a User object looks like:
+
+<p align="center">
+  <img src="images/model-sample.png" alt="Sample user object" />
+<p>
+
+To summarize - the whole SDK is built with objects. Each endpoints, responses
+and models have their own PHP classes with correct typehinting and PHPDoc.
+
+Along with [official Slack documentation](https://api.slack.com/methods), your
+favorite PHP editor should be a good ally to explore the whole API.
+
+## Iterating over pagination
+
+Some Slack API endpoints use a cursor based pagination.
+
+In addition to classical methods, our client provides additional virtual methods
+to ease the iteration over those endpoints. Those methods can be called by
+prefixing the classic method by `iterate`. Here is an example with `usersList()`:
+
+```php
+$userNames = [];
+
+/** @var JoliCode\Slack\Api\Model\ObjsUser $user */
+for ($client->iterateUsersList() as $user) {
+    $userNames[] = $user->getName();
+}
+```
+
+The previous code hide the complexity of working with pagination's cursor. Here
+is the equivalent of the previous code:
+
+```php
+$userNames = [];
+$cursor = '';
+
+do {
+    $response = $client->usersList([
+        'limit' => 200,
+        'cursor' => $cursor,
+    ]);
+
+    /** @var JoliCode\Slack\Api\Model\ObjsUser $user */
+    foreach ($response->getUsers() as $user) {
+        $userNames[] = $user->getName();
+    }
+
+    $cursor = $response->getResponseMetadata() ? $response->getResponseMetadata()->getNextCursor() : '';
+} while (!empty($cursor));
+```
+
+>Note: the virtual methods are not yet documented with PHPDoc so your IDE will
+not autocomplete them.
+
+## Concrete examples
+
+Here are some real-life examples of interacting with the SDK:
+
+- [Posting a message in a Slack channel](https://github.com/jolicode/slack-php-api/tree/main/docs/examples/posting-message.php);
+- [Retrieving the users in a Slack workspace](https://github.com/jolicode/slack-php-api/tree/main/docs/examples/retrieve-users.php);
+
+## Under the hood
+
+This library mainly contains automatically generated code from the official
+[Slack OpenAPI spec](https://github.com/slackapi/slack-api-specs).
+
+Four kinds of PHP classes are included:
+- [endpoints](https://github.com/jolicode/slack-php-api/tree/main/generated/Endpoint) represent the requests made to API methods;
+- [models](https://github.com/jolicode/slack-php-api/tree/main/generated/Model) represent data exchanged with the API;
+- [normalizers](https://github.com/jolicode/slack-php-api/tree/main/generated/Normalizer) transform JSON from the API to PHP models;
+- [runtime](https://github.com/jolicode/slack-php-api/tree/main/generated/Runtime) are classes needed to make Jane work.
+
+If you use the `JoliCode\Slack\ClientFactory` to create the Client (which you
+should), you don't have to understand how the library works internally.
+Calling one of its method will make the HTTP request to the API and return the
+corresponding PHP object.
+
+***
+
+Read more:
+- Next page: [Troubleshoots](3-troubleshoots.md)
+- Previous page: [Get started](1-get-started.md)

docs/2-usage.md

@@ -0,0 +1,45 @@
+# Troubleshoots
+
+Got some problems using this library? Need a missing feature?
+Here is some common troubleshoots.
+
+## Bypassing the incomplete API specification
+
+Slack's OpenAPI spec is not 100% complete yet, hence our generated client may
+miss some features.
+
+If you miss an option in a method, until Slack add it to their spec, we can
+manually add it to our [versioned spec](https://github.com/jolicode/slack-php-api/tree/main/resources/slack-openapi-patched.json) then
+[regenerate](updating-sdk.md) and release a new version of the library.
+
+## Missing data in the DTO?
+
+The Slack specification is not up to date and miss some critical parts. We do
+build a [better one on top of the official](4-updating-sdk.md) but it can't
+be perfect.
+
+What's good is that some models use `\ArrayObject` as base classes so if the
+API returns data we don't have in the OpenAPI mapping, you can still access it via
+Array like syntax:
+
+```php
+$results = $client->searchMessages([
+    'query' => 'test'
+]);
+
+var_dump($results->getOk()); // ok property is mapped
+var_dump($results['messages']); // messages property is not mapped but still readable
+```
+
+Feel free to open issues if you think a model miss some fields.
+
+## Other problems?
+
+The above documentation did not answer your question? Do not hesitate to open
+an issue and share your issue with us.
+
+***
+
+Read more:
+- Next page: [Updating the SDK](4-updating-sdk.md)
+- Previous page: [Usage](2-usage.md)

docs/3-troubleshoots.md

@@ -56,3 +56,9 @@ changes, you can check that the patch is correctly re-applied:
 ```bash
 ./bin/slack-api-client-generator spec:update
 ```
+
+***
+
+Read more:
+- Next page: [Changelog](/changelog)
+- Previous page: [Troubleshoots](3-troubleshoots.md)