Merge pull request #331 from dunglas/improvements

Various docs improvements

Author: dunglas

admin/authentication-support.md

@@ -73,13 +73,11 @@ const fetchWithAuth = (url, options = {}) => {
 
 const restClient = (api) => (hydraClient(api, fetchWithAuth));
 
-class Admin extends Component {
+export default class extends Component {
   render() {
-    return <HydraAdmin entrypoint={entrypoint} restClient={restClient} authClient={authClient}/>
+    return <HydraAdmin entrypoint={entrypoint} restClient={restClient} authClient={authClient}/>;
   }
 }
-
-export default Admin;
 ```
 
 Refer to [the chapter dedicated to authentication in the Admin On Rest documentation](https://marmelab.com/admin-on-rest/Authentication.html)

admin/getting-started.md

@@ -168,7 +168,7 @@ import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocument
 
 const entrypoint = 'https://demo.api-platform.com';
 
-class App extends Component {
+export default class extends Component {
   state = {api: null};
 
   componentDidMount() {
@@ -189,8 +189,6 @@ class App extends Component {
     return <AdminBuilder api={this.state.api} restClient={hydraClient(entrypoint)}/>
   }
 }
-
-export default App;
 ```
 
 Previous chapter: [Introduction](index.md)

admin/handling-relations-to-collections.md

@@ -12,6 +12,7 @@ This API can be created using the following PHP code:
 
 ```php
 <?php
+// src/AppBundle/Entity/Person.php
 
 namespace App\Entity;
 
@@ -40,6 +41,7 @@ class Person
 
 ```php
 <?php
+// src/AppBundle/Entity/Book.php
 
 namespace App\Entity;
 
@@ -128,7 +130,6 @@ Start by adding a "partial search" filter on the `name` property of the `Book` r
 
 ```yaml
 # config/api_filters.yml
-
 services:
     person.search_filter:
         parent: 'api_platform.doctrine.orm.search_filter'

client-generator/react.md

@@ -36,7 +36,6 @@ Bootstrap 4 - from release 0.1.16
   <!-- ... -->
 ```
 
-
 In the app directory, generate the files for the resource you want:
 
     $ generate-api-platform-client https://demo.api-platform.com src/ --resource foo

client-generator/troubleshooting.md

@@ -3,11 +3,11 @@
 * The generator does not perform any authentication, so you must ensure that all referenced Hydra paths for your API are
 accessible anonymously. If you are using API Platform this will at least include:
 
-  ```
-  api_entrypoint                             ANY      ANY      ANY    /{index}.{_format}
-  api_doc                                    ANY      ANY      ANY    /docs.{_format}
-  api_jsonld_context                         ANY      ANY      ANY    /contexts/{shortName}.{_format}
-  ```
+```
+api_entrypoint                             ANY      ANY      ANY    /{index}.{_format}
+api_doc                                    ANY      ANY      ANY    /docs.{_format}
+api_jsonld_context                         ANY      ANY      ANY    /contexts/{shortName}.{_format}
+```
 
 * If you receive `Error: The class http://www.w3.org/ns/hydra/core#ApiDocumentation doesn't exist.` you may have
 specified the documentation URL instead of the entrypoint. For example if you are using API Platform and your
@@ -22,22 +22,22 @@ you are using by running something like `curl https://demo.api-platform.com/`.
 
 * If you receive a message like this:
 
-  ```
-  { Error
-    at done (/usr/local/share/.config/yarn/global/node_modules/jsonld/js/jsonld.js:6851:19)
-    at <anonymous>
-    at process._tickCallback (internal/process/next_tick.js:188:7)
-  name: 'jsonld.InvalidUrl',
-  message: 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object.',
-  details:
-   { code: 'invalid remote context',
-     url: 'https://demo.api-platform.com/contexts/Entrypoint',
-     cause: null } }
-  ```
-
-  Check access to the specified url, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check
-  access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied"
-  message in JSON format was being returned.  
+```
+{ Error
+at done (/usr/local/share/.config/yarn/global/node_modules/jsonld/js/jsonld.js:6851:19)
+at <anonymous>
+at process._tickCallback (internal/process/next_tick.js:188:7)
+name: 'jsonld.InvalidUrl',
+message: 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object.',
+details:
+{ code: 'invalid remote context',
+ url: 'https://demo.api-platform.com/contexts/Entrypoint',
+ cause: null } }
+```
+
+Check access to the specified url, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check
+access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied"
+message in JSON format was being returned.  
 
 Previous chapter: [Vue.js generator](vuejs.md)
 

core/angularjs-integration.md

@@ -1,8 +1,11 @@
-# AngularJS integration
+# AngularJS Integration
+
+Warning: For new project, you should consider using [the API Platform's Progressive Web App generator](../client-generator/index.md)
+(that supports React and Vue.js) instead of this Angular v1 integration.
 
 ## Restangular
 
-ApiPlatformBundle works fine with [AngularJS v1](http://angularjs.org). The popular [Restangular](https://github.com/mgonto/restangular)
+API Platform works fine with [AngularJS v1](http://angularjs.org). The popular [Restangular](https://github.com/mgonto/restangular)
 REST client library for Angular can easily be configured to handle the API format.
 
 Here is a working Restangular config:
@@ -98,4 +101,4 @@ You can look at what we have done as another exemple [api-platform/admin](https:
 
 Previous chapter: [NelmioApiDocBundle integration](nelmio-api-doc.md)
 
-Next chapter: [Swagger Support](swagger.md)
+Next chapter: [Schema Generator: Introduction](../schema-generator/index.md)

core/configuration.md

@@ -4,7 +4,6 @@ Here's the complete configuration of the Symfony bundle with including default v
 
 ```yaml
 # app/config/config.yml
-
 api_platform:
 
     # The title of the API.

core/content-negotiation.md

@@ -42,9 +42,7 @@ and of a custom format called `myformat` and having `application/vnd.myformat` a
 
 ```yaml
 # app/config/config.yml
-
 api_platform:
-
     # ...
 
     formats:
@@ -79,9 +77,7 @@ own implementation of `CustomItemNormalizer`:
 
 ```yaml
 # app/config/services.yml
-
 services:
-
 # ...
 
     'AppBundle\Serializer\CustomItemNormalizer':
@@ -91,7 +87,6 @@ services:
 
 ```php
 <?php
-
 // src/AppBundle/Serializer/CustomItemNormalizer.php
 
 namespace AppBundle\Serializer;
@@ -139,7 +134,6 @@ flatten or remove too complex relations:
 
 ```php
 <?php
-
 // src/AppBundle/Serializer/CustomItemNormalizer.php
 
 namespace AppBundle\Serializer;
@@ -172,6 +166,6 @@ class CustomItemNormalizer implements NormalizerInterface, DenormalizerInterface
 }
 ```
 
-Previous chapter: [The Event System](events.md)
+Previous chapter: [The Serialization Process](core/serialization.md)
 
-Next chapter: [Using External JSON-LD Vocabularies](external-vocabularies.md)
+Next chapter: [Validation](core/validation.md)

core/data-providers.md

@@ -18,7 +18,7 @@ For a given resource, you can implement two kind of interfaces:
   is used when fetching items.
 
 In the following examples we will create custom data providers for an entity class called `AppBundle\Entity\BlogPost`.
-Note, that if your entity is not Doctrine-related, you need to flag the identifier property by using `@ApiProperty(identifier=true)` for things to work properly (see also [Entity Identifier Case](serialization-groups-and-relations.md#entity-identifier-case)).
+Note, that if your entity is not Doctrine-related, you need to flag the identifier property by using `@ApiProperty(identifier=true)` for things to work properly (see also [Entity Identifier Case](serialization.md#entity-identifier-case)).
 
 ## Custom Collection Data Provider
 
@@ -29,7 +29,6 @@ If no data is available, you should return an empty array.
 
 ```php
 <?php
-
 // src/AppBundle/DataProvider/BlogPostCollectionDataProvider.php
 
 namespace AppBundle\DataProvider;
@@ -79,7 +78,6 @@ The `getItem` method can return `null` if no result has been found.
 
 ```php
 <?php
-
 // src/AppBundle/DataProvider/BlogPostItemDataProvider.php
 
 namespace AppBundle\DataProvider;
@@ -118,6 +116,6 @@ services:
         tags: [ 'api_platform.item_data_provider' ]
 ```
 
-Previous chapter: [Extending JSON-LD context](extending-jsonld-context.md)
+Previous chapter: [The Event System](core/events.md)
 
-Next chapter: [Extensions](extensions.md)
+Next chapter: [Extensions](core/extensions.md)

core/default-order.md

@@ -7,7 +7,6 @@ customize this order, you must add an `order` attribute on your ApiResource anno
 
 ```php
 <?php
-
 // src/AppBundle/Entity/Book.php
 
 namespace AppBundle\Entity;
@@ -33,7 +32,6 @@ If you only specify the key, `ASC` direction will be used as default. For exampl
 
 ```php
 <?php
-
 // src/AppBundle/Entity/Book.php
 
 namespace AppBundle\Entity;
@@ -61,8 +59,8 @@ class Book
 
 It's also possible to configure the default filter on an association property:
 
+```php
 <?php
-
 // src/AppBundle/Entity/Book.php
 
 namespace AppBundle\Entity;
@@ -81,6 +79,7 @@ class Book
      */
     public $author;
 }
+```
 
 Previous chapter: [Operations](operations.md)
 

core/events.md

@@ -16,7 +16,6 @@ In the following example, we will send a mail each time a new book is created us
 
 ```php
 <?php
-
 // src/AppBundle/EventSubscriber/BookMailSubscriber.php
 
 namespace AppBundle\EventSubscriber;
@@ -108,4 +107,4 @@ Constant           | Event             | Priority |
 
 Previous chapter: [Pagination](pagination.md)
 
-Next chapter: [Content Negotiation](content-negotiation.md)
+Next chapter: [Data Providers](core/data-providers.md)

core/extending-jsonld-context.md

@@ -6,7 +6,6 @@ within the following annotation, will be passed to the context, that provides a
 
 ```php
 <?php
-
 // src/AppBundle/Entity/Book.php
 
 namespace AppBundle\Entity;
@@ -64,6 +63,6 @@ The generated context will now have your custom attributes set:
 
 Note that you do not have to provide the `@id` attribute, if you do not provide an `@id` attribute, the value from `iri` will be taken.
 
-Previous chapter: [Using External JSON-LD Vocabularies](external-vocabularies.md)
+Previous chapter: [Using External Vocabularies](external-vocabularies.md)
 
-Next chapter: [Data Providers](data-providers.md)
+Next chapter: [FOSUserBundle Integration](core/fosuser-bundle.md)

core/extensions.md

@@ -120,7 +120,6 @@ Finally register the custom extension:
 
 ```yaml
 # app/config/services.yml
-
 services:
 
     # ...
@@ -143,19 +142,16 @@ To secure the access to endpoints, use the following access control rule:
 
 ```yaml
 # app/config/security.yml
-
 security:
-
     # ...
 
     access_control:
-
         # ...
 
         - { path: ^/offers, roles: IS_AUTHENTICATED_FULLY }
         - { path: ^/users, roles: IS_AUTHENTICATED_FULLY }
 ```
 
-Previous chapter: [Data Providers](data-providers.md)
+Previous chapter: [Extensions](core/extensions.md)
 
-Next chapter: [Security](security.md)
+Next chapter: [Security](core/security.md)

core/external-vocabularies.md

@@ -1,4 +1,4 @@
-# Using External JSON-LD Vocabularies
+# Using External Vocabularies
 
 JSON-LD allows to define classes and properties of your API with open vocabularies such as [Schema.org](https://schema.org)
 and [Good Relations](http://www.heppnetz.de/projects/goodrelations/).
@@ -7,7 +7,6 @@ API Platform Core provides annotations usable on PHP classes and properties for
 
 ```php
 <?php
-
 // src/AppBundle/Entity/Book.php
 
 namespace AppBundle\Entity;