From e06508e0e8209231abdcdebfb2e00046f8f38dda Mon Sep 17 00:00:00 2001 From: Remo Meier Date: Sun, 19 Apr 2020 18:49:38 +0200 Subject: [PATCH] documentation updates --- .../src/docs/asciidoc/resource.adoc | 27 +- .../src/docs/releases/latest/info.html | 122 +++++++- .../src/docs/releases/stable/info.html | 271 ++++++------------ .../src/docs/releases/v3.2/info.html | 113 ++++++++ 4 files changed, 336 insertions(+), 197 deletions(-) create mode 100644 crnk-documentation/src/docs/releases/v3.2/info.html diff --git a/crnk-documentation/src/docs/asciidoc/resource.adoc b/crnk-documentation/src/docs/asciidoc/resource.adoc index 466bcb851..ecf72f340 100644 --- a/crnk-documentation/src/docs/asciidoc/resource.adoc +++ b/crnk-documentation/src/docs/asciidoc/resource.adoc @@ -480,15 +480,38 @@ See http://jsonapi.org/format/#document-links for more information about linking } ---- -By default links are serialized as: +Links can be represented either as either simple String: +---- +"http://example.com/articles/1/relationships/comments", +---- + +or as structured objects of type `Link` with +`href`, `rel`, `anchor`, `params`, `describedBy` and `meta` fields: + +---- +"links": { + "self": "http://example.com/articles/1/relationships/comments", + "related": { + "href": "http://example.com/articles/1/comments", + "describedby": "http://example.com/schemas/article-comments", + "meta": { + "count": 10 + } + } + } +} +---- + +`LinksInformation` objects can hold either type. With `DefaultLink` there is a default implementation +of `Link` available. By default simple strings will be serialized as such: ---- "links": { "self": "http://example.com/posts" } ---- -With `crnk.config.serialize.object.links=true` links get serialized as: +This can be changed by setting the property `crnk.config.serialize.object.links=true`: ---- "links": { diff --git a/crnk-documentation/src/docs/releases/latest/info.html b/crnk-documentation/src/docs/releases/latest/info.html index 9e4b0b3ef..6c4557023 100644 --- a/crnk-documentation/src/docs/releases/latest/info.html +++ b/crnk-documentation/src/docs/releases/latest/info.html @@ -1,11 +1,113 @@ +This release provides many incremental improvements over 3.1 together with experimental support for versioning +and more support for the upcoming JSON:API 1.1. + +

Versioning Support (experimental) #238

+ +This release brings experimental support for versioning of resources and fields based on content negotiation. Any resource +and field can carry a version range to specify its availability. Crnk will disregard any resource and field with a version +range that does not intersect with the request version. The HTTP Accept header is used to pass along the desired version +as part of general content negotiation. This has the benefit that URLs remain constant across versions, greatly simplifying +usability and linking. For a more detailed discussion, see here[https://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation/]. +An example looks like: + +
+@JsonApiResource(type = "versionedTask")
+@JsonApiVersion(max = 5)
+public class VersionedTask {
+
+    public enum CompletionStatus {
+        DONE,
+        OPEN,
+        IN_PROGRESS
+    }
+
+    @JsonApiId
+    private Long id;
+
+    private String name;
+
+    @JsonApiVersion(min = 1, max = 3)
+    private boolean completed;
+
+    @JsonApiVersion(min = 5)
+    @JsonProperty("completed")
+    private CompletionStatus newCompleted;
+
+}
+
+ +

+ For more details have a look here. +

+ + +

Support for Object-based Links

+ +Links can be represented as either simple string or structured objects with href, rel, anchor, +params, describedBy and meta. There is a new Link interface and DefaultLink implementation +to model such objects. LinksInformation can now either hold Strings or DefaultLink. An example looks like: + +
+"links": {
+	"self": "http://example.com/articles/1/relationships/comments",
+	"related": {
+		"href": "http://example.com/articles/1/comments",
+		"describedby": "http://example.com/schemas/article-comments",
+		"meta": {
+			"count": 10
+		}
+	}
+}
+
+ +More information can be found in https://jsonapi.org/format/1.1/#document-resource-object-links +and http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation. + +

Misc Improvements

+ \ No newline at end of file +
  • Improved logging for relationship inclusion mechanism. Set io.crnk to DEBUG to learn more + about how inclusions are loaded. +
    • +
  • Re-enabled Spring Boot 1 support upon request to be maintained a little while longer.
    • +
  • JSON-based filter parameters fixed to support renaming of attributes with @JsonProperty.
    • +
  • When using faceted search, the value map is sorted by total count in descending order.
    • +
  • Built-in ExceptionMappers can be overridden by custom ones by implementing the Prioritizable interface.
    • +
  • ExceptionMappers can implement Prioritizable
    • +
  • More documentation for ExceptionMappers
    • +
  • Meta-model is excluded from OpenAPI generation by default. #625
    • +
  • Non-ID fields can no longer be named id.
    • +
  • Bulk support through the BulkResourceRepository interface now supports HTTP DELETE operations. + This complements existing support for POST. PATCH has not yet been implemented. +
    • +
  • JPA repositories avoid issuing a count query in some situations where the configured offset, limit and + received result sets allow to by-pass it. Greatly improving performance in some situations! Where every bit of + performance is essential, the existing "has more" strategy rather than total count may also be of help. +
    • +
  • JAX-RS integration has an improved path handling. There will be some more work to harden this area + in the future to account for the different behavior of different frameworks. +
    • +
  • Refinements to the JPA-related documentation. For example, + how to implement more advanced use cases where the entity and resource model do not fully match. +
    • +
  • + Better error message when the parsing of an enum parameter fails. +
    • +
  • The order of attributes is honored in the serialized REST documents. Attributes in the implementation and on the REST layer will have + the same order. +
    • +
  • A bug fix when resolving attribute paths from subtypes of a resource #712.
    • +
  • Improvements to the Typescript generation for the java.util.Map data type #709
    • +
  • The CrnkExceptionMapper uses the JSON:API error fields title and code if detail is not available for better + error messages. +
    • +
  • New UrlBuilder interface introduced as public API that allows to customize the construction of URLs out of resource ids and QuerySpecs.
    • + + + +

    Acknowledgements

    + +A special thanks to Broad, Ralph, JB, PoffM, Christian, Sebastian, +Kokogino, duncanportelli, Luka, Gianin, fjf2002, Tomasz, erjaimin for all +the contributions to make this release happen! + diff --git a/crnk-documentation/src/docs/releases/stable/info.html b/crnk-documentation/src/docs/releases/stable/info.html index b75932967..f1bad35bf 100644 --- a/crnk-documentation/src/docs/releases/stable/info.html +++ b/crnk-documentation/src/docs/releases/stable/info.html @@ -1,212 +1,113 @@ -This release provides many incremental improvements to 3.0 while introducing three major new features. +This release provides many incremental improvements over 3.1 together with experimental support for versioning +and more support for the upcoming JSON:API 1.1. +

    Versioning Support (experimental) #238

    -

    OpenAPI Support (experimental)

    - -Experimental support for OpenAPI is now available as extension to the Crnk generator. It will generate -an OpenAPI schema out of any Crnk endpoint by inspecting the implementation and derive a schema. An -example setup looks like: +This release brings experimental support for versioning of resources and fields based on content negotiation. Any resource +and field can carry a version range to specify its availability. Crnk will disregard any resource and field with a version +range that does not intersect with the request version. The HTTP Accept header is used to pass along the desired version +as part of general content negotiation. This has the benefit that URLs remain constant across versions, greatly simplifying +usability and linking. For a more detailed discussion, see here[https://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation/]. +An example looks like: 
    -buildscript {
-    dependencies {
-        classpath "io.crnk:crnk-gen-gradle:${version}"
+@JsonApiResource(type = "versionedTask")
+@JsonApiVersion(max = 5)
+public class VersionedTask {
+
+    public enum CompletionStatus {
+        DONE,
+        OPEN,
+        IN_PROGRESS
     }
-}
-
-apply plugin: 'crnk-gen'
-    crnkGen {
-        runtime {
-            configuration = 'openapiGenRuntime'
-        }
-
-        // fork generation into new process to have clean environment
-        forked = true
 
-        // specify the package to look for resources
-        resourcePackages = ['io.crnk.test']
+    @JsonApiId
+    private Long id;
 
-        openapi {
-            // enable OpenAPI generation within Gradle plugin
-            enabled = true
+    private String name;
 
-            // specify name of openapi template in the build dir to merge onto
-            templateName = "openapi-template.yml"
+    @JsonApiVersion(min = 1, max = 3)
+    private boolean completed;
 
-            // specify name of API to display in the generated OpenAPI file
-            projectName = "Generated Title"
+    @JsonApiVersion(min = 5)
+    @JsonProperty("completed")
+    private CompletionStatus newCompleted;
 
-            // specify version of the API to display in the generated OpenAPI file
-            projectVersion = "0.1.0"
-
-            // specify name of openapi template in the build dir to merge onto
-            projectDescription = "A generated description of the API."
-
-            // specify location of generated sources
-            genDir = file('src/resources')
-        }
-    }
 }
-crnkGen.init()
    -Fore more information see here. -Have a look at the GitHub - tickets -for the future roadmap. +

    + For more details have a look here. +

    -

    Bulk Repositories (experimental)

    +

    Support for Object-based Links

    -There is a new experimental BulkResourceRepository that closely resembles ResourceRepository but -takes multiple resources as arguments. This give the repository the possibility to optimize -bulk mutations of multiple resources, like sharing a database transaction. - -Currently only POST is implemented, not PATCH and DELETE yet! More information can be -found here. -In future releases this will be aligned with support for the upcoming JSON:API 1.1 specification. +Links can be represented as either simple string or structured objects with href, rel, anchor, +params, describedBy and meta. There is a new Link interface and DefaultLink implementation +to model such objects. LinksInformation can now either hold Strings or DefaultLink. An example looks like: 
    -public class BulkInMemoryRepository implements BulkResourceRepository<Task, Long> {
-
-    @Override
-    public <S extends T> List<S> create(List<S> resources) {
-       ...
-    }
-
-    ...
+"links": {
+	"self": "http://example.com/articles/1/relationships/comments",
+	"related": {
+		"href": "http://example.com/articles/1/comments",
+		"describedby": "http://example.com/schemas/article-comments",
+		"meta": {
+			"count": 10
+		}
+	}
 }
    +More information can be found in https://jsonapi.org/format/1.1/#document-resource-object-links +and http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation. -

    TestKit

    - -There is a new project io.crnk:crnk-testkit to facilitate testing of JSON:API based endpoints. -As first contribution there is a RandomWalkLinkChecker: +

    Misc Improvements

    -
    -CrnkClient client = ...
-HttpAdapter httpAdapter = client.getHttpAdapter();
-
-RandomWalkLinkChecker linkChecker = new RandomWalkLinkChecker(httpAdapter);
-linkChecker.setWalkLength(100);
-linkChecker.addStartUrl(...)
-
-linkChecker.performCheck();
-
    - -It performs a random walk on an API endpoint by following the links as specified by JSON:API. It -will verify that each links provides a valid 2xx response code. By having a sufficiently long walk, -it will ensure that any GET request can be served with high probability. This in turn allows -developers to focus on testing business functionality, while lower layer REST details like linking get -verified automatically. - -More information and roadmap are available here. + -

    Minor Improvements

    +

    Acknowledgements

    - +A special thanks to MacLeod Broad, Ralph Marchildon, JB, PoffM, Christian Gendreau, Sebastian Wyrazik, +Kokogino, duncanportelli, Luka Lodrant, Gianin Basler, fjf2002, Tomasz Staniaszek, erjaimin for all +the contributions to make this release happen! diff --git a/crnk-documentation/src/docs/releases/v3.2/info.html b/crnk-documentation/src/docs/releases/v3.2/info.html new file mode 100644 index 000000000..f1bad35bf --- /dev/null +++ b/crnk-documentation/src/docs/releases/v3.2/info.html @@ -0,0 +1,113 @@ +This release provides many incremental improvements over 3.1 together with experimental support for versioning +and more support for the upcoming JSON:API 1.1. + +

    Versioning Support (experimental) #238

    + +This release brings experimental support for versioning of resources and fields based on content negotiation. Any resource +and field can carry a version range to specify its availability. Crnk will disregard any resource and field with a version +range that does not intersect with the request version. The HTTP Accept header is used to pass along the desired version +as part of general content negotiation. This has the benefit that URLs remain constant across versions, greatly simplifying +usability and linking. For a more detailed discussion, see here[https://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation/]. +An example looks like: + +
    +@JsonApiResource(type = "versionedTask")
+@JsonApiVersion(max = 5)
+public class VersionedTask {
+
+    public enum CompletionStatus {
+        DONE,
+        OPEN,
+        IN_PROGRESS
+    }
+
+    @JsonApiId
+    private Long id;
+
+    private String name;
+
+    @JsonApiVersion(min = 1, max = 3)
+    private boolean completed;
+
+    @JsonApiVersion(min = 5)
+    @JsonProperty("completed")
+    private CompletionStatus newCompleted;
+
+}
+
    + +

    + For more details have a look here. +

    + + +

    Support for Object-based Links

    + +Links can be represented as either simple string or structured objects with href, rel, anchor, +params, describedBy and meta. There is a new Link interface and DefaultLink implementation +to model such objects. LinksInformation can now either hold Strings or DefaultLink. An example looks like: + +
    +"links": {
+	"self": "http://example.com/articles/1/relationships/comments",
+	"related": {
+		"href": "http://example.com/articles/1/comments",
+		"describedby": "http://example.com/schemas/article-comments",
+		"meta": {
+			"count": 10
+		}
+	}
+}
+
    + +More information can be found in https://jsonapi.org/format/1.1/#document-resource-object-links +and http://www.crnk.io/releases/latest/documentation/#_jsonapilinksinformation. + +

    Misc Improvements

    + + + + +

    Acknowledgements

    + +A special thanks to MacLeod Broad, Ralph Marchildon, JB, PoffM, Christian Gendreau, Sebastian Wyrazik, +Kokogino, duncanportelli, Luka Lodrant, Gianin Basler, fjf2002, Tomasz Staniaszek, erjaimin for all +the contributions to make this release happen! +