What about putting the whole semantic specification (f.k.a. Data Dictionary PDF) directly within the OpenAPI document?

[patricekrakow]

Since the description properties do support the (full?) markdown syntax and since we have decided to define (almost) all the properties locally, we do have a new opportuinity (compared to the XML time) to maintain the semantic specification directly within the OpenAPI document, instead of using a separate file (i.e. papiNet-API.md).

Please vote for this proposal using the "thumbs up" or the "thumbs down" icon.

[patricekrakow]

Let's have a try, I can transfer the current content of papiNet-API.md within the papiNet-API.yaml. We also need to update the papiNet JSON Style Guide, adding the rule that we should not add a description to the self-explanatory properties or values, e.g. meter.

[patricekrakow]

Here is an example:

purchaseOrderNumber:
  type: string
  minLength: 1
  description: |
    This is the identifier of the _purchase order_ as assigned by the _customer_.

[larsolofsson]

How to insert a line break in a description text? The pipe "|" character seems not to be supported by the swagger editor.

It would not look nice and be bad readability in the swagger editor if line breaks are not supported in description texts, especially in a description text for a property including definitions of all enumerations of the property.

[patricekrakow]

We can close this issue, it's clear that we want to put the semantic specifications of each property within the JSON Schema using the description property, as JSON Schema allows the full power of markdown.