Skip to content

Commit e06508e

Browse files
remmeierremmeier
committed
documentation updates
1 parent 789aa4b commit e06508e

File tree

4 files changed

+336
-197
lines changed

4 files changed

+336
-197
lines changed

‎crnk-documentation/src/docs/asciidoc/resource.adoc

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -480,15 +480,38 @@ See http://jsonapi.org/format/#document-links for more information about linking
480480
}
481481
----
482482

483-
By default links are serialized as:
483+
Links can be represented either as either simple String:
484484

485+
----
486+
"http://example.com/articles/1/relationships/comments",
487+
----
488+
489+
or as structured objects of type `Link` with
490+
`href`, `rel`, `anchor`, `params`, `describedBy` and `meta` fields:
491+
492+
----
493+
"links": {
494+
"self": "http://example.com/articles/1/relationships/comments",
495+
"related": {
496+
"href": "http://example.com/articles/1/comments",
497+
"describedby": "http://example.com/schemas/article-comments",
498+
"meta": {
499+
"count": 10
500+
}
501+
}
502+
}
503+
}
504+
----
505+
506+
`LinksInformation` objects can hold either type. With `DefaultLink` there is a default implementation
507+
of `Link` available. By default simple strings will be serialized as such:
485508
----
486509
"links": {
487510
"self": "http://example.com/posts"
488511
}
489512
----
490513

491-
With `crnk.config.serialize.object.links=true` links get serialized as:
514+
This can be changed by setting the property `crnk.config.serialize.object.links=true`:
492515

493516
----
494517
"links": {

‎crnk-documentation/src/docs/releases/latest/info.html

Lines changed: 112 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,113 @@
1+
This release provides many incremental improvements over 3.1 together with experimental support for versioning
2+
and more support for the upcoming JSON:API 1.1.
3+
4+
<h4>Versioning Support (experimental) <a href="https://github.com/crnk-project/crnk-framework/issues/238">#238</a></h4>
5+
6+
This release brings experimental support for versioning of resources and fields based on content negotiation. Any resource
7+
and field can carry a version range to specify its availability. Crnk will disregard any resource and field with a version
8+
range that does not intersect with the request version. The HTTP Accept header is used to pass along the desired version
9+
as part of general content negotiation. This has the benefit that URLs remain constant across versions, greatly simplifying
10+
usability and linking. For a more detailed discussion, see here[https://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation/].
11+
An example looks like:
12+
13+
<pre class="prettyprint">
14+
@JsonApiResource(type = "versionedTask")
15+
@JsonApiVersion(max = 5)
16+
public class VersionedTask {
17+
18+
public enum CompletionStatus {
19+
DONE,
20+
OPEN,
21+
IN_PROGRESS
22+
}
23+
24+
@JsonApiId
25+
private Long id;
26+
27+
private String name;
28+
29+
@JsonApiVersion(min = 1, max = 3)
30+
private boolean completed;
31+
32+
@JsonApiVersion(min = 5)
33+
@JsonProperty("completed")
34+
private CompletionStatus newCompleted;
35+
36+
}
37+
</pre>
38+
39+
<p>
40+
For more details have a look <a href="http://www.crnk.io/releases/latest/documentation/#_jsonapiversion">here</a>.
41+
</p>
42+
43+
44+
<h4>Support for Object-based Links</h4>
45+
46+
Links can be represented as either simple string or structured objects with <code>href</code>, <code>rel</code>, <code>anchor</code>,
47+
<code>params</code>, <code>describedBy</code> and <code>meta</code>. There is a new <code>Link</code> interface and DefaultLink implementation
48+
to model such objects. <code>LinksInformation</code> can now either hold Strings or <code>DefaultLink</code>. An example looks like:
49+
50+
<pre class="prettyprint">
51+
"links": {
52+
"self": "http://example.com/articles/1/relationships/comments",
53+
"related": {
54+
"href": "http://example.com/articles/1/comments",
55+
"describedby": "http://example.com/schemas/article-comments",
56+
"meta": {
57+
"count": 10
58+
}
59+
}
60+
}
61+
</pre>
62+
63+
More information can be found in <a href="https://jsonapi.org/format/1.1/#document-resource-object-links">https://jsonapi.org/format/1.1/#document-resource-object-links</a>
64+
and <a href="http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation">http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation</a>.
65+
66+
<h4>Misc Improvements</h4>
67+
168
<ul>
2-
<li>Improved logging for relationship inclusion mechanism. Set <code>io.crnk</code> to DEBUG to learn more
3-
about how inclusions are loaded.
4-
</li>
5-
<li>Reenabled Spring Boot 1 support.</li>
6-
<li>JSON-based filter parameters fixed to support renaming of attributes with @JsonProperty.</li>
7-
<li>When using faceted search, the value map is sorted by total count in descending order.</li>
8-
<li>Built-in ExceptionMappers can be overriden by custom ones</li>
9-
<li>ExceptionMappers can implement Prioritizable</li>
10-
<li>More documentation for ExceptionMappers</li>
11-
</ul>
69+
<li>Improved logging for relationship inclusion mechanism. Set <code>io.crnk</code> to DEBUG to learn more
70+
about how inclusions are loaded.
71+
</li>
72+
<li>Re-enabled Spring Boot 1 support upon request to be maintained a little while longer.</li>
73+
<li>JSON-based filter parameters fixed to support renaming of attributes with @JsonProperty.</li>
74+
<li>When using faceted search, the value map is sorted by total count in descending order.</li>
75+
<li>Built-in ExceptionMappers can be overridden by custom ones by implementing the Prioritizable interface.</li>
76+
<li>ExceptionMappers can implement Prioritizable</li>
77+
<li>More documentation for ExceptionMappers</li>
78+
<li>Meta-model is excluded from OpenAPI generation by default. <a href="https://github.com/crnk-project/crnk-framework/issues/625">#625</a></li>
79+
<li>Non-ID fields can no longer be named <code>id</code>.</li>
80+
<li>Bulk support through the BulkResourceRepository interface now supports HTTP DELETE operations.
81+
This complements existing support for POST. PATCH has not yet been implemented.
82+
</li>
83+
<li>JPA repositories avoid issuing a count query in some situations where the configured offset, limit and
84+
received result sets allow to by-pass it. Greatly improving performance in some situations! Where every bit of
85+
performance is essential, the existing "has more" strategy rather than total count may also be of help.
86+
</li>
87+
<li>JAX-RS integration has an improved path handling. There will be some more work to harden this area
88+
in the future to account for the different behavior of different frameworks.
89+
</li>
90+
<li>Refinements to the <a href="http://www.crnk.io/releases/latest/documentation/#_jpa">JPA-related documentation</a>. For example,
91+
how to implement more advanced use cases where the entity and resource model do not fully match.
92+
</li>
93+
<li>
94+
Better error message when the parsing of an enum parameter fails.
95+
</li>
96+
<li>The order of attributes is honored in the serialized REST documents. Attributes in the implementation and on the REST layer will have
97+
the same order.
98+
</li>
99+
<li>A bug fix when resolving attribute paths from subtypes of a resource <a href="https://github.com/crnk-project/crnk-framework/issues/712">#712</a>.</li>
100+
<li>Improvements to the Typescript generation for the java.util.Map data type <a href="https://github.com/crnk-project/crnk-framework/issues/709">#709</a></li>
101+
<li>The CrnkExceptionMapper uses the JSON:API error fields <code>title</code> and <code>code</code> if <code>detail</code> is not available for better
102+
error messages.
103+
</li>
104+
<li>New UrlBuilder interface introduced as public API that allows to customize the construction of URLs out of resource ids and QuerySpecs.</li>
105+
</ul>
106+
107+
108+
<h4>Acknowledgements</h4>
109+
110+
A special thanks to Broad, Ralph, JB, PoffM, Christian, Sebastian,
111+
Kokogino, duncanportelli, Luka, Gianin, fjf2002, Tomasz, erjaimin for all
112+
the contributions to make this release happen!
113+

0 commit comments

Comments
 (0)