Some new docs, release notes (#191)

* Extra docs for queries

* Update changelog & readme

Author: joukevandermaas

CHANGELOG.md

@@ -1,5 +1,21 @@
 ## `master` (upcoming 1.7)
 
+- [**BUGFIX**] Serialise complex objects correctly (#149 by @laurence79)
+- [**BUGFIX**] Do not require Accept header (#151 by @bjornharrtell)
+- [**FEATURE**] Optional links support (#153 by @bjornharrtell)
+- [**BUGFIX**] Fix regression missing 'data' key for relationships when using DisableDefaultIncluded (#155 by @bjornharrtell)
+- [**FEATURE**] Add support for metadata (#158)
+- [**BUGFIX**] Omit data for relationship objects not existing as property in the original model (#161 by @bjornharrtell)
+- [**FEATURE**] Pagination page size (#165 by @erikhejl, #170 by @sergey-litvinov-work)
+- [**FEATURE**] Configuration improvments (formatter can be only add at end of the collection, without deleting other formatters) (#168 by @tomasjurasek)
+- [**FEATURE**] Functionality to return list of HttpErrors instead of just one error (#172 by @sergey-litvinov-work)
+- [**FEATURE**] Added deserialization method to `JsonApiSerializer<T>` (#179 @madsphi)
+- [**FEATURE**] Provide ability to handle JsonApi parameters in WebApi action itself manually (#181 by @sergey-litvinov-work)
+- [**MAINTENANCE**] Upgrade xunit dependencies (#183 by @bjornharrtell)
+- [**BUGFIX**] Fix regression with omitted data (#184 by @bjornharrtell)
+- [**FEATURE**] Opt into JsonApi per webapi endpoint (#187, #189 by @barsh)
+- [**FEATURE**] Option to serialize attributes in camelCase (#190 by @barsh)
+
 ## Version 1.6
 
 - [**BUGFIX**] Support belongsTo relationships when data is null (#124 by @goo32)

README.md

@@ -115,3 +115,13 @@ GET http://example.com/people/123
 
 Deserialization works just like in normal Web API; you don't need
 to do anything special to make this work.
+
+### Creating a new release
+
+Follow the steps below to create a new release:
+
+1. Create a branch called `release-v<version>` (e.g. `release-v1.5`)
+2. Increase the version number in `appveyor.yml` in `master`
+3. Push both changes and wait for the build
+4. Copy the release notes into the release description on Github
+5. Publish the new release

docs/content/7-queryable-endpoints.md

@@ -25,7 +25,8 @@ public IQueryable<Person> GetPeople()
 }
 ```
 
-> **Note**: Saule only supports the `sort` and `filter` query parameters.
+> **Note**: Saule supports the `sort`, `include` (for relationships) and `filter`
+> query parameters.
 > The same attribute may support other queries in the future.
 
 ```
@@ -180,4 +181,79 @@ public static void Register(HttpConfiguration config)
 
     config.ConfigureJsonApi(jsonApiConfig);
 }
-```
+```
+
+## Disabling default includes
+
+By default, Saule includes all available relationships in the response. If this is
+not what you want, you can disable this behavior using the `DisableDefaultIncludedAttribute`.
+When you add this attribute to an action method, it will only include relationships
+specifically requested by clients using the `include` query parameter.
+
+Note that even if you do not use this attribute, if the client provides the `include` parameter,
+Saule will not include anything that was not requested. For example, if your `Person` model
+has `Job` and `Friends` relationships, and the client requests `include=friends`, `Job` will
+not be returned in the response.
+
+## Manually handling queries
+
+Saule can apply sorting, filtering, includes and pagination to responses
+automatically. If you would rather do this yourself, or if your setup is
+not compatible with Saules implementation, you can also manually apply the
+query parameters. In order to do this, you must use the `HandlesQueryAttribute`:
+
+```csharp
+[ReturnsResource(typeof(PersonResource))]
+public class PeopleController : ApiController
+{
+    [HttpGet]
+    [HandlesQuery]
+    [Paginated]
+    [Route("people")]
+    public IEnumerable<Person> GetPeople(QueryContext context)
+    {
+        IEnumerable<Person> data = GetSomePeople();
+
+        bool? hideLastName;
+        // if we want to include car or job, then we return response as is as it already has them
+        // otherwise we clear it
+        bool includeCar = context.Include.Includes.Any(p => p.Name == nameof(Person.Car));
+        bool includeJob = context.Include.Includes.Any(p => p.Name == nameof(Person.Job));
+
+        context.Filter.TryGetValue("HideLastName", out hideLastName);
+
+        if (hideLastName.GetValueOrDefault() || !includeCar)
+        {
+            foreach (var person in data)
+            {
+                if (hideLastName.GetValueOrDefault())
+                {
+                    person.LastName = null;
+                }
+
+                if (!includeCar)
+                    person.Car = null;
+
+                if (!includeJob)
+                    person.Job = null;
+            }
+        }
+
+        int? minAge;
+        if (context.Filter.TryGetValue("MinAge", out minAge) && minAge.HasValue)
+        {
+            data = data.Where(person => person.Age >= minAge);
+        }
+
+        if (context.Pagination.PerPage.HasValue)
+        {
+            data = data.Take(context.Pagination.PerPage.Value);
+        }
+
+        return data;
+    }
+}
+```
+
+The `QueryContext` parameter value is provided by Saule and contains the query
+information requested by the client.