migrate remaining docs

Author: jaredcnance

docs/getting-started/intro.md

@@ -10,7 +10,6 @@ The shortest path to a running API looks like:
 - 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.
@@ -128,13 +127,6 @@ public void Configure(
 }
 ```
 
-### Run Migrations
-
-```
-dotnet ef migrations add AddPeople
-dotnet ef database update
-```
-
 ### Start the App
 
 ```

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

@@ -1,6 +1,3 @@
-- name: Introduction
-  href: intro.md
-
 - name: Installation
   href: install.md
 

docs/getting-started/toc.yml

@@ -0,0 +1,108 @@
+# Controllers
+
+You need to create controllers that inherit from `JsonApiController<TEntity>`
+
+```c#
+public class ArticlesController : JsonApiController<Article>
+{
+    public ArticlesController(
+        IJsonApiContext jsonApiContext,
+        IResourceService<Article> resourceService,
+        ILoggerFactory loggerFactory) 
+    : base(jsonApiContext, resourceService, loggerFactory)
+    { }
+}
+```
+        
+## Non-Integer Type Keys
+
+If your model is using a type other than int for the primary key, you must explicitly declare it in the controller and service generic type definitions.
+
+```c#
+public class ArticlesController : JsonApiController<Article, Guid>
+//---------------------- ^^^^
+{
+    public ArticlesController(
+        IJsonApiContext jsonApiContext,
+        IResourceService<Article, Guid> resourceService,
+        //--------------------- ^^^^
+
+        ILoggerFactory loggerFactory) 
+    : base(jsonApiContext, resourceService, loggerFactory)
+    { }
+}
+```
+        
+## Resource Access Control
+
+It is often desirable to limit what methods are exposed on your controller. The first way, you can do this is to simply inherit from `BaseJsonApiController` and explicitly declare what methods are available.
+
+In this example, if a client attempts to do anything other than GET a resource, an HTTP 404 Not Found response will be returned since no other methods are exposed.
+
+This approach is ok, but introduces some boilerplate that can easily be avoided.
+
+```c#
+public class ArticlesController : BaseJsonApiController<Article>
+{
+    public ArticlesController(
+        IJsonApiContext jsonApiContext,
+        IResourceService<Article> resourceService) 
+    : base(jsonApiContext, resourceService)
+    { }
+
+    [HttpGet]
+    public override async Task<IActionResult> GetAsync() 
+        => await base.GetAsync();
+
+    [HttpGet("{id}")]
+    public override async Task<IActionResult> GetAsync(TId id) 
+        => await base.GetAsync(id);
+}
+```
+        
+## Using ActionFilterAttributes
+
+The next option is to use the ActionFilterAttributes that ship with the library. The available attributes are:
+
+- `NoHttpPost`: disallow POST requests
+- `NoHttpPatch`: disallow PATCH requests
+- `NoHttpDelete`: disallow DELETE requests
+- `HttpReadOnly`: all of the above
+
+Not only does this reduce boilerplate, but it also provides a more meaningful HTTP response code. 
+An attempt to use one blacklisted methods will result in a HTTP 405 Method Not Allowed response.
+
+```c#
+[HttpReadOnly]
+public class ArticlesController : BaseJsonApiController<Article>
+{
+    public ArticlesController(
+        IJsonApiContext jsonApiContext,
+        IResourceService<Article> resourceService) 
+    : base(jsonApiContext, resourceService)
+    { }
+}
+```
+        
+## Implicit Access By Service Injection
+
+Finally, you can control the allowed methods by supplying only the available service implementations. In some cases, resources may be an aggregation of entities or a view on top of the underlying entities. In these cases, there may not be a writable IResourceService implementation. In these cases, simply inject the implementation that is available.
+
+As with the ActionFilterAttributes, if a service implementation is not available to service a request, HTTP 405 Method Not Allowed will be returned.
+
+For more information about resource injection, see the next section titled Resource Services.
+
+```c#
+public class ReportsController : BaseJsonApiController<Report> 
+{
+    public ReportsController(
+        IJsonApiContext jsonApiContext, 
+        IGetAllService<Report> getAll)
+    : base(jsonApiContext, getAll: getAll)
+    { }
+
+    [HttpGet]
+    public override async Task<IActionResult> GetAsync() 
+        => await base.GetAsync();
+}
+```

docs/usage/extensibility/controllers.md

@@ -0,0 +1,9 @@
+# Custom Query Formats
+
+For information on the default query parameter formats, see the documentation for each query method.
+
+In order to customize the query formats, you need to implement the `IQueryParser` interface and inject it.
+
+```c#
+services.AddScoped<IQueryParser, FooQueryParser>();
+```

docs/usage/extensibility/custom-query-formats.md

@@ -0,0 +1,54 @@
+# Layer Overview
+
+By default, data retrieval is distributed across 3 layers:
+
+JsonApiController (required)
+
+└── EntityResourceService: IResourceService
+
+     └── DefaultEntityRepository: IEntityRepository
+
+Customization can be done at any of these layers. However, it is recommended that you make your customizations at the service or the repository layer when possible to keep the controllers free of unnecessary logic. 
+You can use the following as a general rule of thumb for where to put business logic:
+
+- `Controller`: simple validation logic that should result in the return of specific HTTP status codes such as model validation
+- `IResourceService`: advanced BL and replacement of data access mechanisms
+- `IEntityRepository`: custom logic that builds on the EF APIs, such as Authorization of data
+
+## Replacing Services
+
+**Note:** If you are using auto-discovery, services will be automatically registered for you.
+
+Replacing services is done on a per resource basis and can be done through simple DI in your Startup.cs file.
+
+In v3.0.0 we introduced an extenion method that you should use to
+register services. This method handles some of the common issues
+users have had with service registration.
+
+```c#
+// Startup.cs
+public IServiceProvider ConfigureServices(IServiceCollection services)
+{
+    // custom service
+    services.AddResourceService<FooService>();
+
+    // custom repository
+    services.AddScoped<AFooRepository>();
+}
+```
+
+Prior to v3.0.0 you could do it like so:
+
+```c#
+// Startup.cs
+public IServiceProvider ConfigureServices(IServiceCollection services)
+{
+    // custom service
+    services.AddScoped<IEntityRepository<Foo>, FooService>();
+
+    // custom repository
+    services.AddScoped<IEntityRepository<Foo>, FooService>();
+
+    // ...
+}
+```

docs/usage/extensibility/layer-overview.md

@@ -0,0 +1,12 @@
+# Middleware
+Add the following to your Startup.ConfigureServices method. Replace AppDbContext with your DbContext.
+
+```c3
+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.
+
+```c3
+app.UseJsonApi();
+```

docs/usage/extensibility/middleware.md

@@ -0,0 +1,99 @@
+# Entity Repositories
+
+If you want to use EF, but need additional data access logic (such as authorization), you can implement custom methods for accessing the data by creating an implementation of IEntityRepository<Entity, TId>. If you only need minor changes you can override the methods defined in DefaultEntityRepository<TEntity, TId>.
+
+The repository should then be add to the service collection in Startup.cs.
+
+```c#
+public IServiceProvider ConfigureServices(IServiceCollection services) 
+{
+    services.AddScoped<IEntityRepository<Article>, AuthorizedArticleRepository>();
+    // ...
+}
+```
+
+A sample implementation that performs data authorization might look like this.
+
+All of the methods in the DefaultEntityRepository will use the Get() method to get the DbSet<TEntity> so this is a good method to apply scoped filters such as user or tenant authorization.
+
+```c#
+public class AuthorizedArticleRepository 
+  : DefaultEntityRepository<Article>
+{
+    private readonly IAuthenticationService _authenticationService;
+
+    public AuthorizedArticleRepository(
+        ILoggerFactory loggerFactory,
+        IJsonApiContext jsonApiContext,
+        IDbContextResolver contextResolver,
+        IAuthenticationService authenticationService)
+    : base(loggerFactory, jsonApiContext, contextResolver)
+    {
+        _authenticationService = authenticationService;
+    }
+
+    public override IQueryable<MyEntity> Get() 
+        => base.Get()
+            .Where(e => 
+                e.UserId == _authenticationService.UserId
+            );
+}
+```
+
+## Multiple DbContexts
+
+If you need to use multiple EF DbContext, first add each DbContext to the ContextGraphBuilder.
+
+Then, create an implementation of IDbContextResolver for each context.
+
+Register each of the new IDbContextResolver implementations in the Startup.
+
+You can then create a general repository for each context and inject it per resource type. This example shows a single DbContextARepository for all entities that are members of DbContextA.
+
+Then inject the repository for the correct entity, in this case Foo is a member of DbContextA.
+
+```c#
+// Startup.cs
+services.AddJsonApi(options => {
+  options.BuildContextGraph((builder) =>
+  {
+      // Add both contexts using the builder
+      builder.AddDbContext<DbContextA>();
+      builder.AddDbContext<DbContextB>();
+  });
+}, mvcBuilder);
+
+
+public class DbContextAResolver : IDbContextResolver
+{
+    private readonly DbContextA _context;
+
+    public DbContextAResolver(DbContextA context)
+    {
+        _context = context;
+    }
+
+    public DbContext GetContext() => _context;
+}
+
+
+// Startup.cs
+services.AddScoped<DbContextAResolver>();
+services.AddScoped<DbContextBResolver>();
+
+
+public class DbContextARepository<TEntity> 
+: DefaultEntityRepository<TEntity> where TEntity : class, IIdentifiable<T>
+{
+  public DbContextARepository(
+      ILoggerFactory loggerFactory,
+      IJsonApiContext jsonApiContext,
+      DbContextAResolver contextResolver)
+  : base(loggerFactory, jsonApiContext, contextResolver)
+  { }
+}
+
+
+// Startup.cs
+services.AddScoped<IEntityRepository<Foo>, DbContextARepository<Foo>>();
+```