Skip to content

Commit 62812b6

Browse files
jaredcnancejaredcnance
committed
update docs
1 parent 2547678 commit 62812b6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+1990
-115
lines changed

Diff for: ‎JsonApiDotnetCore.sln

+2-15
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ResourceEntitySeparationExa
4545
EndProject
4646
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ResourceEntitySeparationExampleTests", "test\ResourceEntitySeparationExampleTests\ResourceEntitySeparationExampleTests.csproj", "{6DFA30D7-1679-4333-9779-6FB678E48EF5}"
4747
EndProject
48-
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GettingStarted", "src\Examples\GettingStarted\GettingStarted.csproj", "{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}"
48+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GettingStarted", "src\Examples\GettingStarted\GettingStarted.csproj", "{DF9BFD82-D937-4907-B0B4-64670417115F}"
4949
EndProject
5050
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DiscoveryTests", "test\DiscoveryTests\DiscoveryTests.csproj", "{09C0C8D8-B721-4955-8889-55CB149C3B5C}"
5151
EndProject
@@ -190,19 +190,7 @@ Global
190190
{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x64.ActiveCfg = Release|Any CPU
191191
{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x64.Build.0 = Release|Any CPU
192192
{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.ActiveCfg = Release|Any CPU
193-
{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.Build.0 = Release|Any CPU
194-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
195-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|Any CPU.Build.0 = Debug|Any CPU
196-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x64.ActiveCfg = Debug|Any CPU
197-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x64.Build.0 = Debug|Any CPU
198-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x86.ActiveCfg = Debug|Any CPU
199-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Debug|x86.Build.0 = Debug|Any CPU
200-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|Any CPU.ActiveCfg = Release|Any CPU
201-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|Any CPU.Build.0 = Release|Any CPU
202-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x64.ActiveCfg = Release|Any CPU
203-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x64.Build.0 = Release|Any CPU
204-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x86.ActiveCfg = Release|Any CPU
205-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71}.Release|x86.Build.0 = Release|Any CPU
193+
{6DFA30D7-1679-4333-9779-6FB678E48EF5}.Release|x86.Build.0 = Release|Any CPU\
206194
{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
207195
{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|Any CPU.Build.0 = Debug|Any CPU
208196
{09C0C8D8-B721-4955-8889-55CB149C3B5C}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -233,7 +221,6 @@ Global
233221
{9CD2C116-D133-4FE4-97DA-A9FEAFF045F1} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
234222
{F4097194-9415-418A-AB4E-315C5D5466AF} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
235223
{6DFA30D7-1679-4333-9779-6FB678E48EF5} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
236-
{9B2A5AD7-0BF4-472E-A1B4-8BB623FDEB71} = {026FBC6C-AF76-4568-9B87-EC73457899FD}
237224
{09C0C8D8-B721-4955-8889-55CB149C3B5C} = {24B15015-62E5-42E1-9BA0-ECE6BE7AA15F}
238225
EndGlobalSection
239226
GlobalSection(ExtensibilityGlobals) = postSolution

Diff for: ‎docs/.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_site/
2+
*.manifest

Diff for: ‎docs/README.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Running
2+
3+
```
4+
./generate.sh
5+
docfx ./docfx.json --serve
6+
```

Diff for: ‎docs/api/.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
###############
2+
# temp file #
3+
###############
4+
*.yml

Diff for: ‎src/JsonApiDotNetCore/api/.manifest renamed to ‎docs/api/.manifest

+205-74
Large diffs are not rendered by default.

Diff for: ‎src/JsonApiDotNetCore/api/index.md renamed to ‎docs/api/index.md

File renamed without changes.

Diff for: ‎src/JsonApiDotNetCore/docfx.json renamed to ‎docs/docfx.json

+6-4
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
{
44
"src": [
55
{
6-
"files": [ "**.csproj" ],
7-
"src": "C:\\Users\\jnance\\dev\\json-api-dotnet-core\\src\\JsonApiDotNetCore"
6+
"files": [ "**/JsonApiDotNetCore.csproj" ],
7+
"src": "../"
88
}
99
],
1010
"dest": "api",
@@ -21,8 +21,10 @@
2121
},
2222
{
2323
"files": [
24-
"articles/**.md",
25-
"articles/**/toc.yml",
24+
"getting-started/**.md",
25+
"getting-started/**/toc.yml",
26+
"usage/**.md",
27+
"request-examples/**.md",
2628
"toc.yml",
2729
"*.md"
2830
]

Diff for: ‎docs/generate.sh

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#!/bin/bash
2+
# generates ./request-examples documents
3+
4+
function cleanup() {
5+
kill -9 $(lsof -ti tcp:5001) &2>/dev/null
6+
}
7+
8+
cleanup
9+
dotnet run -p ../src/Examples/GettingStarted/GettingStarted.csproj &
10+
app_pid=$!
11+
echo "Started app with PID $app_pid"
12+
13+
rm -rf ./request-examples/*.json
14+
rm -rf ./request-examples/*.temp
15+
16+
{ # try
17+
sleep 10
18+
19+
echo "sleep over"
20+
21+
for path in ./request-examples/*.sh; do
22+
op_name=$(basename "$path" .sh)
23+
file="./request-examples/$op_name-Response.json"
24+
temp_file="./request-examples/$op_name-Response.temp"
25+
26+
# 1. execute bash script
27+
# 2. redirect stdout to a temp file, this will be the JSON output
28+
# 3. redirect stderr to JSON file, this will be the curl verbose output
29+
# we grab the last line, trim the prefix, add some newlines and the push
30+
# it to the top of the JSON file
31+
bash $path \
32+
1> >(jq . > $temp_file) \
33+
2> >(grep "HTTP" | tail -n 1 | cut -c 3- | awk '{ printf "%s\n\n",$0 }' > "./request-examples/$op_name-Response.json")
34+
35+
# append the actual JSON to the file
36+
cat $temp_file >> $file
37+
rm $temp_file
38+
done
39+
}
40+
41+
# docfx metadata
42+
43+
cleanup

Diff for: ‎docs/generators/index.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Installing
2+
3+
...
4+
5+
## Creating a project template
6+
7+
```
8+
dotnet new jadnc
9+
```

Diff for: ‎docs/getting-started/install.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Installation
2+
3+
Click [here](https://www.nuget.org/packages/JsonApiDotnetCore/) for the latest NuGet version.
4+
5+
```
6+
dotnet add package JsonApiDotnetCore
7+
```
8+
9+
```powershell
10+
Install-Package JsonApiDotnetCore
11+
```
12+
13+
```xml
14+
<ItemGroup>
15+
<!-- Be sure to check NuGet for the latest version # -->
16+
<PackageReference Include="JsonApiDotNetCore" Version="3.0.0" />
17+
</ItemGroup>
18+
```
19+
20+
## Pre-Release Packages
21+
22+
Occasionally we will release experimental features as pre-release packages on our
23+
MyGet feed. You can download these by adding [the pacakge feed](https://www.myget.org/feed/Details/research-institute) to your nuget configuration.
24+
25+
These releases are deployed from the `develop` branch directly.
26+
27+
```xml
28+
<?xml version="1.0" encoding="utf-8"?>
29+
<configuration>
30+
<packageSources>
31+
<add key="JADNC Pre-Release" value="https://www.myget.org/F/research-institute/api/v3/index.json" />
32+
</packageSources>
33+
</configuration>
34+
```

Diff for: ‎docs/getting-started/step-by-step.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Step-By-Step Guide to a Running API
2+
3+
The most basic use case leverages Entity Framework.
4+
The shortest path to a running API looks like:
5+
6+
- Create a new web app
7+
- Install
8+
- Define models
9+
- Define the DbContext
10+
- Define controllers
11+
- Add Middleware and Services
12+
- Seed the database
13+
- Start the app
14+
15+
This page will walk you through the **simplest** use case. More detailed examples can be found in the detailed usage subsections.
16+
17+
### Create A New Web App
18+
19+
```
20+
mkdir MyApp
21+
cd MyApp
22+
dotnet new webapi
23+
```
24+
25+
### Install
26+
27+
```
28+
dotnet add package JsonApiDotnetCore
29+
30+
- or -
31+
32+
Install-Package JsonApiDotnetCore
33+
```
34+
35+
### Define Models
36+
37+
Define your domain models such that they implement `IIdentifiable<TId>`.
38+
The easiest way to do this is to inherit `Identifiable`
39+
40+
```c#
41+
public class Person : Identifiable
42+
{
43+
[Attr("name")]
44+
public string Name { get; set; }
45+
}
46+
```
47+
48+
### Define DbContext
49+
50+
Nothing special here, just an ordinary `DbContext`
51+
52+
```
53+
public class AppDbContext : DbContext
54+
{
55+
public AppDbContext(DbContextOptions<AppDbContext> options)
56+
: base(options) { }
57+
58+
public DbSet<Person> People { get; set; }
59+
}
60+
```
61+
62+
### Define Controllers
63+
64+
You need to create controllers that inherit from `JsonApiController<TEntity>` or `JsonApiController<TEntity, TId>`
65+
where `TEntity` is the model that inherits from `Identifiable<TId>`
66+
67+
```c#
68+
public class PeopleController : JsonApiController<Person>
69+
{
70+
public PeopleController(
71+
IJsonApiContext jsonApiContext,
72+
IResourceService<Person> resourceService,
73+
ILoggerFactory loggerFactory)
74+
: base(jsonApiContext, resourceService, loggerFactory)
75+
{ }
76+
}
77+
```
78+
79+
### Middleware and Services
80+
81+
Finally, add the services by adding the following to your Startup.ConfigureServices:
82+
83+
```c#
84+
public IServiceProvider ConfigureServices(IServiceCollection services)
85+
{
86+
// add the db context like you normally would
87+
services.AddDbContext<AppDbContext>(options =>
88+
{ // use whatever provider you want, this is just an example
89+
options.UseNpgsql(GetDbConnectionString());
90+
}, ServiceLifetime.Transient);
91+
92+
// add jsonapi dotnet core
93+
services.AddJsonApi<AppDbContext>();
94+
// ...
95+
}
96+
```
97+
98+
Add the middleware to the Startup.Configure method. Note that under the hood,
99+
this will call `app.UseMvc()` so there is no need to add that as well.
100+
101+
```c#
102+
public void Configure(IApplicationBuilder app)
103+
{
104+
app.UseJsonApi();
105+
}
106+
```
107+
108+
### Seeding the Database
109+
110+
One way to seed the database is in your Configure method:
111+
112+
```c#
113+
public void Configure(
114+
IApplicationBuilder app,
115+
AppDbContext context)
116+
{
117+
context.Database.EnsureCreated();
118+
if(context.People.Any() == false)
119+
{
120+
context.People.Add(new Person {
121+
Name = "John Doe"
122+
});
123+
context.SaveChanges();
124+
}
125+
// ...
126+
app.UseJsonApi();
127+
}
128+
```
129+
130+
### Start the App
131+
132+
```
133+
dotnet run
134+
curl http://localhost:5000/people
135+
```
136+

Diff for: ‎docs/getting-started/toc.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
- name: Installation
2+
href: install.md
3+
4+
- name: Step By Step
5+
href: step-by-step.md

Diff for: ‎docs/index.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# JSON API .Net Core
2+
3+
A [{ json:api }](https://jsonapi.org) web application framework for .Net Core.
4+
5+
## Objectives
6+
7+
### 1. Eliminate Boilerplate
8+
9+
The goal of this package is to facility the development of json:api applications that leverage the full range
10+
of features provided by the specification.
11+
12+
Eliminate CRUD boilerplate and provide the following features across all your resource endpoints:
13+
14+
- Relationship inclusion and navigation
15+
- Filtering
16+
- Sorting
17+
- Pagination
18+
- Sparse field selection
19+
- Checkout the [example requests](request-examples) to see the kind of features you will get out of the box
20+
21+
### 2. Extensibility
22+
23+
This library relies heavily on an open-generic-based dependency injection model which allows for easy per-resource customization.
24+

Diff for: ‎docs/request-examples/.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*.json
2+
*.temp

Diff for: ‎docs/request-examples/000-CREATE_Person.sh

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
curl -vs http://localhost:5001/api/people \
2+
-H "Accept: application/vnd.api+json" \
3+
-H "Content-Type: application/vnd.api+json" \
4+
-d '{
5+
"data": {
6+
"type": "people",
7+
"attributes": {
8+
"name": "Alice"
9+
}
10+
}
11+
}'

Diff for: ‎docs/request-examples/001-CREATE_Article.sh

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
curl -vs http://localhost:5001/api/articles \
2+
-H "Accept: application/vnd.api+json" \
3+
-H "Content-Type: application/vnd.api+json" \
4+
-d '{
5+
"data": {
6+
"type": "articles",
7+
"attributes": {
8+
"title": "Moby"
9+
},
10+
"relationships": {
11+
"author": {
12+
"data": {
13+
"type": "people",
14+
"id": "1"
15+
}
16+
}
17+
}
18+
}
19+
}'

Diff for: ‎docs/request-examples/002-GET_Articles.sh

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

Diff for: ‎docs/request-examples/003-GET_Article.sh

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

Diff for: ‎docs/request-examples/004-GET_Articles_With_Authors.sh

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

0 commit comments

Comments
 (0)