Promote belgif validator and rest-problem-java (#198)

+ add paragraph titles to intro section
+ also add links in README.md

README.md

@@ -24,6 +24,13 @@ Types in beta status are in the source code, but not part of the released artifa
 | money | [latest release](https://github.com/belgif/openapi-money/releases/latest) | [OpenAPI (dev version)](https://github.com/belgif/openapi-money/blob/master/src/main/openapi/money/v1/money-v1.yaml)|
 | healthcare | [latest release](https://github.com/belgif/openapi-healthcare/releases/latest) | [OpenAPI (dev version)](https://github.com/belgif/openapi-healthcare/blob/master/src/main/openapi/healthcare/v1/healthcare-v1.yaml)|
 
+# Related tools
+
+The [https://github.com/belgif/rest-guide-validator](belgif-rest-guide-validator) validates compliance of OpenAPI documents to the REST guide. 
+
+The [https://github.com/belgif/rest-problem-java](belgif-rest-problem-java) library can be used to implement error handling in Java REST clients and server implementations, using standardized Problem messages as listed in the REST guide.
+
+
 # Guidelines to write the styleguide
 
 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the REST styleguide are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).

guide/src/main/asciidoc/api_specifications.adoc

@@ -564,7 +564,7 @@ Following tools can be used to edit OpenAPI files
 |Name|Link| Description
 |Swagger UI | https://swagger.io/swagger-ui/ | Browser application. Graphical and text view of Swagger files. Does not support references to external files.
 |Zalando's Swagger plugin | https://github.com/zalando/intellij-swagger | Open Source plugin for IntelliJ. Text-only editor.
-|Stoplight Studio | https://stoplight.io/studio/ | Commercial editor with a free version. Graphical and text view, both web based or as desktop application. Supports validation of API style guides (https://stoplight.io/open-source/spectral[Spectral]).
+|Stoplight Studio | https://github.com/stoplightio/studio/releases | Commercial editor with a free version. Graphical and text view, both web based or as desktop application. Supports validation of API style guides (https://stoplight.io/open-source/spectral[Spectral]).
 |42Crunch OpenAPI (Swagger) Editor for VS Code|https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi|Open Source plugin for Visual Studio Code. Text editor with SwaggerUI preview and multi-file support.
 |42Crunch OpenAPI (Swagger) Editor for IntelliJ|https://plugins.jetbrains.com/plugin/14837-openapi-swagger-editor|Plugin for IntelliJ. Text editor with multi-file support.
 |IntelliJ OpenAPI Specifications |https://www.jetbrains.com/help/idea/openapi.html|Plugin bundled with IntelliJ Ultimate (commercial). Text editor with SwaggerUI preview and multi-file support.
@@ -579,6 +579,18 @@ Following tools can be used to generate server stubs and API client libraries fr
 |swagger-codegen| https://github.com/swagger-api/swagger-codegen|
 |===
 
+Following tools allow to verify REST styleguide rules for an OpenAPI document:
+
+|===
+|Name | Link | Comments
+
+|belgif-rest-guide-validator | https://github.com/belgif/rest-guide-validator | Open Source Maven Plugin to validate OpenAPI document against rules in this guide
+
+|Spectral a| https://stoplight.io/open-source/spectral | Open Source tool (javascript-based) to enforce REST styleguide rules.
+
+_Note:_ There currently is no implementation of this REST guide for Spectral.
+
+|===
 === References
 
 [options="header"]

guide/src/main/asciidoc/errorhandling.adoc

@@ -1,3 +1,4 @@
+[[chapter-error-handling]]
 == Error handling
 
 === Problem Details
@@ -226,6 +227,7 @@ They are defined as URNs of format `+urn:problem-type:belgif:<type>+`.
 
 WARNING: `href` links to descriptions of standardized problem types will change in the future to recommended format containing full problem type identifier without HTML extension. Current URLs will redirect.
 
+The library https://github.com/belgif/rest-problem-java[`belgif-rest-problem-java`] provides implementation support for these problem types when developing Java applications.
 
 include::problems/badRequest.adoc[leveloffset=3]
 

guide/src/main/asciidoc/introduction.adoc

@@ -7,20 +7,28 @@ This guide is a living document, updated when new interoperability issues arise
 All changes are reviewed by the REST design workgroup, in which the Belgian government organizations are represented.
 If you find errors or omissions, or want to contribute, you can open an issue or pull request on https://github.com/belgif/rest-guide[GitHub].
 
+*Why choose RESTful web services?*
+
 The main benefit for choosing RESTful services is to increase flexibility and to offer web service support to client platforms not able to communicate using SOAP web services.
 
 * REST is the defacto standard to communicate with web services from JavaScript and native mobile applications.
 * While SOAP is strictly linked to XML and needs complex standards (MTOM, Soap-with-Attachments) to work with other media formats, RESTful services can support this natively.
 * WS-* specifications added to SOAP are often overly complex and redundant to the possibilities over the underlying communication protocol (e.g. HTTP).
 * REST has become the industry standard for developing APIs on the web (https://developers.google.com/apis-explorer[Google^], https://developers.facebook.com/docs/graph-api/reference[Facebook^], https://developer.amazon.com/public/apis[Amazon^], https://dev.twitter.com/rest/public[Twitter^], etc).
 
-Topics not covered in this guide:
 
-* Securing REST APIs. Guidelines are under development by the REST Security Working Group, based on the OpenID Connect and https://tools.ietf.org/html/rfc6749[OAuth 2.0^] standards.
-* Semantics of common business data (e.g. social security number, address, ...). These are managed by the REST Functional Working Group in the https://github.com/belgif/fedvoc[belgif fedvoc repository].
+*Related Belgif initiatives*
+
+These Belgif resources may also be useful when developing RESTful webservices:
+
 * OpenAPI specifications for common data types can be found in the https://github.com/belgif?q=openapi&type=&language=[openapi-* GitHub repositories].
+* The https://github.com/belgif/rest-guide-validator[belgif-rest-guide-validator] validates compliance of OpenAPI documents to this guide.
+* The https://github.com/belgif/rest-problem-java[belgif-rest-problem-java] library can be used to implement error handling in Java REST clients and server implementations, using <<chapter-error-handling,standardized Problem messages>>.
+* Semantics of common business data (e.g. social security number, address, ...) are maintained by the REST Functional Working Group in the https://github.com/belgif/fedvoc[Belgif FedVoc repository].
+* Securing REST APIs. Guidelines are under development by the REST Security Working Group, based on the OpenID Connect and https://tools.ietf.org/html/rfc6749[OAuth 2.0^] standards.
+
+*Links*
 
-.Links
 ****
 * Sources: https://github.com/belgif/rest-guide
 * Issues: https://github.com/belgif/rest-guide/issues
@@ -29,7 +37,7 @@ Topics not covered in this guide:
 
 [NOTE]
 ====
-For brevity most URIs in examples are shortened, but in practice URIs should be in absolute notation.
+For brevity most URLs in JSON examples are shortened, but in practice they should be in absolute notation.
 ====
 
 [[license]]