DocFx Documentation

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
@@ -190,19 +190,7 @@ Global
 		{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x64.ActiveCfg = Release|Any CPU
 		{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x64.Build.0 = Release|Any CPU
 		{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.ActiveCfg = Release|Any CPU
-		{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.Build.0 = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x64.Build.0 = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x86.Build.0 = Debug|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|Any CPU.Build.0 = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x64.ActiveCfg = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x64.Build.0 = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x86.ActiveCfg = Release|Any CPU
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x86.Build.0 = Release|Any CPU
+		{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.Build.0 = Release|Any CPU\
 		{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -233,7 +221,6 @@ Global
 		{9CD2C116-D133-4FE4-97DA-A9FEAFF045F1} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
 		{F4097194-9415-418A-AB4E-315C5D5466AF} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
 		{6DFA30D7-1679-4333-9779-6FB678E48EF5} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
-		{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
 		{09C0C8D8-B721-4955-8889-55CB149C3B5C} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution

docs/.gitignore

@@ -0,0 +1,2 @@
+_site/
+*.manifest

docs/README.md

@@ -0,0 +1,6 @@
+# Running
+
+```
+./generate.sh
+docfx ./docfx.json --serve
+```

docs/api/.gitignore

@@ -0,0 +1,4 @@
+###############
+#  temp file  #
+###############
+*.yml

src/JsonApiDotNetCore/docfx.json → docs/docfx.json

@@ -3,8 +3,8 @@
         {
             "src": [
                 {
-                    "files": [ "**.csproj" ],
-                    "src": "C:\\Users\\jnance\\dev\\json-api-dotnet-core\\src\\JsonApiDotNetCore"
+                    "files": [ "**/JsonApiDotNetCore.csproj" ],
+                    "src": "../"
                 }
             ],
             "dest": "api",
@@ -21,8 +21,10 @@
             },
             {
                 "files": [
-                    "articles/**.md",
-                    "articles/**/toc.yml",
+                    "getting-started/**.md",
+                    "getting-started/**/toc.yml",
+                    "usage/**.md",
+                    "request-examples/**.md",
                     "toc.yml",
                     "*.md"
                 ]

docs/generate.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# generates ./request-examples documents
+
+function cleanup() {
+    kill -9 $(lsof -ti tcp:5001) &2>/dev/null
+}
+
+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
+    sleep 10
+
+    echo "sleep over"
+
+    for path in ./request-examples/*.sh; do
+        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
+}
+
+# docfx metadata
+
+cleanup

docs/generators/index.md

@@ -0,0 +1,9 @@
+## Installing
+
+...
+
+## Creating a project template
+
+```
+dotnet new jadnc
+```

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,136 @@
+# 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
+- 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();
+}
+```
+
+### Start the App
+
+```
+dotnet run
+curl http://localhost:5000/people
+```
+

docs/getting-started/toc.yml

@@ -0,0 +1,5 @@
+- name: Installation
+  href: install.md
+
+- name: Step By Step
+  href: step-by-step.md

docs/index.md

@@ -0,0 +1,24 @@
+# JSON API .Net Core
+
+A [{ json:api }](https://jsonapi.org) web application framework for .Net Core.
+
+## Objectives
+
+### 1. Eliminate Boilerplate
+
+The goal of this package is to facility the development of json:api applications that leverage the full range 
+of features provided by the specification.
+
+Eliminate CRUD boilerplate and provide the following features across all your resource endpoints: 
+
+- Relationship inclusion and navigation
+- Filtering
+- Sorting
+- Pagination
+- Sparse field selection
+- 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

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

docs/request-examples/000-CREATE_Person.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/001-CREATE_Article.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": "Moby"
+                },
+                "relationships": {
+                    "author": {
+                        "data": {
+                            "type": "people",
+                            "id": "1"
+                        }
+                    }
+                }
+            }
+        }'

docs/request-examples/002-GET_Articles.sh

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

docs/request-examples/003-GET_Article.sh

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

docs/request-examples/004-GET_Articles_With_Authors.sh

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