@arc-e-tect/api-only-publisher 0.13.1 → 0.14.1

package/README.adoc

@@ -6,7 +6,15 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.13.1
+:api-only-publisher-version: 0.14.1
+
+[NOTE]
+.About this documentation
+====
+This documentation was partially authored by Claude, an AI assistant.
+Documentation is part of the product, and is held to the same standard as the code it describes.
+If something here seems wrong, please file a bug report: link:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/issues/new[open an issue in this repository ↗].
+====
 
 image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
 image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
@@ -1021,11 +1029,19 @@ AsyncAPI operation '<operationId>': message '<messageKey>' (<fragment, or where
 ----
 
 For OpenAPI, it is whether a request body's or response's media type declares `example`/`examples`, or the schema it references carries its own top-level `examples`.
-Nothing downstream currently reads an OpenAPI example, so the message never claims the bundle cannot be used -- only that the generated documentation is weaker without one:
+The message never claims the bundle cannot be used, and says only what is true for the part.
+For a request body, the TranscriberJ's contract cases send the example the media type names, or values from the schemas' own examples (link:../api-only-transcriberj/README.adoc#example-data[Example data in the TranscriberJ's README →]); without one they send values it generates:
+
+[source,text]
+----
+OpenAPI operation '<operationId>': request body (<fragment, or where in the bundle>) carries no example, so the TranscriberJ's contract cases send generated values rather than ones the contract chose, and the generated documentation is harder to read.
+----
+
+Nothing downstream reads a response's example, so for a response only the documentation is weaker without one:
 
 [source,text]
 ----
-OpenAPI operation '<operationId>': <request body, or response <status>> (<fragment, or where in the bundle>) carries no example, which makes the generated documentation harder to read.
+OpenAPI operation '<operationId>': response <status> (<fragment, or where in the bundle>) carries no example, which makes the generated documentation harder to read.
 ----
 
 A body or response with no `content` at all, such as a `204`, has nothing to exemplify and is never reported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/examples.js

@@ -16,10 +16,12 @@
 // Object itself. A message with none cannot be used for Microcks-based conformance
 // testing at all, so the message says exactly that.
 //
-// OpenAPI: nothing downstream currently reads an example. The TranscriberJ
-// processes a bundle without one perfectly well -- bodies take arguments,
-// constraints become constants. So the OpenAPI message claims only what is true:
-// weaker documentation, never that the bundle cannot be used.
+// OpenAPI: the TranscriberJ sends a request body's named example, or values from
+// the schemas' own examples, in the contract cases it generates; without them it
+// generates values from the constraints, and processes the bundle perfectly well.
+// A response's example is read by nothing downstream. So the OpenAPI message
+// claims only what is true for its part -- generated values for a request body,
+// weaker documentation for both -- never that the bundle cannot be used.
 
 const KEY = "x-fragment-path";
 
@@ -160,8 +162,12 @@ function asyncapiMessage(finding) {
  */
 function openapiMessage(finding) {
     const where = finding.fragmentPath || `at ${finding.at}`;
-    return `OpenAPI operation '${finding.operationId}': ${finding.part} (${where}) ` +
-        "carries no example, which makes the generated documentation harder to read.";
+    const prefix = `OpenAPI operation '${finding.operationId}': ${finding.part} (${where}) carries no example, `;
+    if (finding.part === "request body") {
+        return prefix + "so the TranscriberJ's contract cases send generated values rather than ones the " +
+            "contract chose, and the generated documentation is harder to read.";
+    }
+    return prefix + "which makes the generated documentation harder to read.";
 }
 
 module.exports = {