improve example requests and add step-by-step

Author: jaredcnance

JsonApiDotnetCore.sln

@@ -45,7 +45,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ResourceEntitySeparationExa
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ResourceEntitySeparationExampleTests", "test\ResourceEntitySeparationExampleTests\ResourceEntitySeparationExampleTests.csproj", "{6DFA30D7-1679-4333-9779-6FB678E48EF5}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GettingStarted", "src\Examples\GettingStarted\GettingStarted.csproj", "{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GettingStarted", "src\Examples\GettingStarted\GettingStarted.csproj", "{DF9BFD82-D937-4907-B0B4-64670417115F}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DiscoveryTests", "test\DiscoveryTests\DiscoveryTests.csproj", "{09C0C8D8-B721-4955-8889-55CB149C3B5C}"
 EndProject

docs/generate.sh

@@ -8,19 +8,33 @@ function cleanup() {
 cleanup
 dotnet run -p ../src/Examples/GettingStarted/GettingStarted.csproj &
 app_pid=$!
+echo "Started app with PID $app_pid"
 
+rm -rf ./request-examples/*.json
+rm -rf ./request-examples/*.temp
 
 { # try
-    echo "Started app with PID $app_pid"
-
-    sleep 5
+    sleep 10
 
     echo "sleep over"
 
     for path in ./request-examples/*.sh; do
-        op_name=$(basename "$path" .sh | sed 's/.*-//')
-        echo $op_name
-        bash $path | jq . > "./request-examples/$op_name-Response.json"
+        op_name=$(basename "$path" .sh)
+        file="./request-examples/$op_name-Response.json"
+        temp_file="./request-examples/$op_name-Response.temp"
+
+        # 1. execute bash script
+        # 2. redirect stdout to a temp file, this will be the JSON output
+        # 3. redirect stderr to JSON file, this will be the curl verbose output
+        #    we grab the last line, trim the prefix, add some newlines and the push
+        #    it to the top of the JSON file
+        bash $path \
+            1> >(jq . > $temp_file) \
+            2> >(grep "HTTP" | tail -n 1 | cut -c 3- | awk '{ printf "%s\n\n",$0 }' > "./request-examples/$op_name-Response.json")
+
+        # append the actual JSON to the file
+        cat $temp_file >> $file
+        rm $temp_file
     done
 }
 

docs/getting-started/install.md

@@ -0,0 +1,34 @@
+# Installation
+
+Click [here](https://www.nuget.org/packages/JsonApiDotnetCore/) for the latest NuGet version.
+
+```
+dotnet add package JsonApiDotnetCore
+```
+
+```powershell
+Install-Package JsonApiDotnetCore
+```
+
+```xml
+<ItemGroup>
+  <!-- Be sure to check NuGet for the latest version # -->
+  <PackageReference Include="JsonApiDotNetCore" Version="3.0.0" />
+</ItemGroup>
+```
+
+## Pre-Release Packages
+
+Occasionally we will release experimental features as pre-release packages on our
+MyGet feed. You can download these by adding [the pacakge feed](https://www.myget.org/feed/Details/research-institute) to your nuget configuration.
+
+These releases are deployed from the `develop` branch directly.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <add key="JADNC Pre-Release" value="https://www.myget.org/F/research-institute/api/v3/index.json" />
+  </packageSources>
+</configuration>
+```

docs/getting-started/step-by-step.md

@@ -0,0 +1,144 @@
+# Step-By-Step Guide to a Running API
+
+The most basic use case leverages Entity Framework. 
+The shortest path to a running API looks like:
+
+- Create a new web app
+- Install
+- Define models
+- Define the DbContext
+- Define controllers
+- Add Middleware and Services
+- Seed the database
+- Run Migrations
+- Start the app
+
+This page will walk you through the **simplest** use case. More detailed examples can be found in the detailed usage subsections.
+
+### Create A New Web App
+
+```
+mkdir MyApp
+cd MyApp
+dotnet new webapi
+```
+
+### Install
+
+```
+dotnet add package JsonApiDotnetCore
+
+- or -
+
+Install-Package JsonApiDotnetCore
+```
+
+### Define Models
+        
+Define your domain models such that they implement `IIdentifiable<TId>`.
+The easiest way to do this is to inherit `Identifiable`
+
+```c#
+public class Person : Identifiable
+{ 
+    [Attr("name")]
+    public string Name { get; set; }
+}
+```
+
+### Define DbContext
+        
+Nothing special here, just an ordinary `DbContext`
+
+```
+public class AppDbContext : DbContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options)
+        : base(options) { }
+        
+    public DbSet<Person> People { get; set; }
+}
+```
+
+### Define Controllers
+        
+You need to create controllers that inherit from `JsonApiController<TEntity>` or `JsonApiController<TEntity, TId>`
+where `TEntity` is the model that inherits from `Identifiable<TId>`
+
+```c#
+public class PeopleController : JsonApiController<Person>
+{
+    public PeopleController(
+        IJsonApiContext jsonApiContext,
+        IResourceService<Person> resourceService,
+        ILoggerFactory loggerFactory) 
+    : base(jsonApiContext, resourceService, loggerFactory)
+    { }
+}
+```
+
+### Middleware and Services
+
+Finally, add the services by adding the following to your Startup.ConfigureServices:
+
+```c#
+public IServiceProvider ConfigureServices(IServiceCollection services)
+{
+    // add the db context like you normally would
+    services.AddDbContext<AppDbContext>(options =>
+    { // use whatever provider you want, this is just an example
+        options.UseNpgsql(GetDbConnectionString());
+    }, ServiceLifetime.Transient);
+
+    // add jsonapi dotnet core
+    services.AddJsonApi<AppDbContext>();
+    // ...
+}
+```
+
+Add the middleware to the Startup.Configure method. Note that under the hood, 
+this will call `app.UseMvc()` so there is no need to add that as well.
+
+```c#
+public void Configure(IApplicationBuilder app)
+{
+    app.UseJsonApi();
+}
+```
+
+### Seeding the Database
+
+One way to seed the database is in your Configure method:
+
+```c#
+public void Configure(
+    IApplicationBuilder app,
+    AppDbContext context)
+{
+    context.Database.EnsureCreated();
+    if(context.People.Any() == false) 
+    {
+        context.People.Add(new Person {
+            Name = "John Doe"
+        });
+        context.SaveChanges();
+    }
+    // ...
+    app.UseJsonApi();
+}
+```
+
+### Run Migrations
+
+```
+dotnet ef migrations add AddPeople
+dotnet ef database update
+```
+
+### Start the Ap
+
+```
+dotnet run
+curl http://localhost:5000/people
+```
+

docs/getting-started/toc.yml

@@ -1,2 +1,8 @@
 - name: Introduction
   href: intro.md
+
+- name: Installation
+  href: install.md
+
+- name: Step By Step
+  href: step-by-step.md

docs/index.md

@@ -16,21 +16,9 @@ Eliminate CRUD boilerplate and provide the following features across all your re
 - Sorting
 - Pagination
 - Sparse field selection
-- And more...
-
-As an example, with just the following model and controller definitions, you can service all of the following requests:
-
-```http
-GET /articles HTTP/1.1
-Accept: application/vnd.api+json
-```
-
-[!code-csharp[Article](../src/Examples/GettingStarted/Models/Article.cs)]
-
-[!code-csharp[ArticlesController](../src/Examples/GettingStarted/Controllers/ArticlesController.cs)]
+- Checkout the [example requests](request-examples) to see the kind of features you will get out of the box
 
 ### 2. Extensibility
 
 This library relies heavily on an open-generic-based dependency injection model which allows for easy per-resource customization.
 
-

docs/request-examples/.gitignore

@@ -1 +1,2 @@
-*.json
+*.json
+*.temp

docs/request-examples/000-CREATE_Article.sh

@@ -0,0 +1,11 @@
+curl -vs http://localhost:5001/api/people           \
+    -H "Accept: application/vnd.api+json"           \
+    -H "Content-Type: application/vnd.api+json"     \
+    -d '{
+            "data": {
+                "type": "people",
+                "attributes": {
+                    "name": "Alice"
+                }
+            }
+        }'

docs/request-examples/000-CREATE_Person.sh

@@ -0,0 +1,19 @@
+curl -vs http://localhost:5001/api/articles         \
+    -H "Accept: application/vnd.api+json"           \
+    -H "Content-Type: application/vnd.api+json"     \
+    -d '{
+            "data": {
+                "type": "articles",
+                "attributes": {
+                    "title": "test"
+                },
+                "relationships": {
+                    "author": {
+                        "data": {
+                            "type": "people",
+                            "id": "1"
+                        }
+                    }
+                }
+            }
+        }'

docs/request-examples/001-CREATE_Article.sh

@@ -0,0 +1,2 @@
+curl -vs http://localhost:5001/api/articles     \
+    -H "Accept: application/vnd.api+json"

docs/request-examples/001-GET_Articles.sh

@@ -0,0 +1,2 @@
+curl -vs http://localhost:5001/api/articles/1     \
+    -H "Accept: application/vnd.api+json"

docs/request-examples/002-GET_Article.sh

@@ -0,0 +1,2 @@
+curl -vs http://localhost:5001/api/articles?include=author     \
+    -H "Accept: application/vnd.api+json"

docs/request-examples/002-GET_Articles.sh

@@ -0,0 +1,20 @@
+# Request Examples
+
+To update these requests:
+
+1. Add a bash (.sh) file prefixed by a number that is used to determine the order the scripts are executed. The bash script should execute a request and output the response. Example:
+```
+curl -vs http://localhost:5001/api/articles     \
+    -H "Accept: application/vnd.api+json"
+```
+
+2. Add the example to `index.md`. Example:
+```
+## Get Article with Author
+
+[!code-sh[GET Request](004-GET_Articles_With_Authors.sh)]
+[!code-json[GET Response](004-GET_Articles_With_Authors-Response.json)]
+```
+
+3. Run `./generate.sh`
+4. Verify the results by running `docfx --serve`

docs/request-examples/003-GET_Article.sh

@@ -2,18 +2,28 @@
 
 These requests have been generated against the "GettingStarted" application and are updated on every deployment.
 
+## Create Person
+
+[!code-sh[CREATE](000-CREATE_Person.sh)]
+[!code-json[CREATE](000-CREATE_Person-Response.json)]
+
 ## Create Article
 
-[!code-sh[CREATE](000-CREATE_Article.sh)]
-[!code-json[CREATE](CREATE_Article-Response.json)]
+[!code-sh[CREATE](001-CREATE_Article.sh)]
+[!code-json[CREATE](001-CREATE_Article-Response.json)]
 
 
 ## Get All Articles
 
-[!code-sh[GET Request](001-GET_Articles.sh)]
-[!code-json[GET Response](GET_Articles-Response.json)]
+[!code-sh[GET Request](002-GET_Articles.sh)]
+[!code-json[GET Response](002-GET_Articles-Response.json)]
 
 ## Get Article By Id
 
-[!code-sh[GET Request](002-GET_Article.sh)]
-[!code-json[GET Response](GET_Article-Response.json)]
+[!code-sh[GET Request](003-GET_Article.sh)]
+[!code-json[GET Response](003-GET_Article-Response.json)]
+
+## Get Article with Author
+
+[!code-sh[GET Request](004-GET_Articles_With_Authors.sh)]
+[!code-json[GET Response](004-GET_Articles_With_Authors-Response.json)]

docs/request-examples/004-GET_Articles_With_Authors.sh

@@ -1,4 +1,5 @@
 using JsonApiDotNetCore.Models;
+
 namespace GettingStarted.Models
 {
     public class Article : Identifiable