New Resource Property node facet: notes?


#1

For your consideration,

In the interest of using the RAML to fully document an interface it is often necessary to to provide more detailed information to document special use cases or additional table or lists of coded values for an implementer. This additional information would not be appropriate in the description node as it could be far too verbose.

Currently tools such as Anypoint Designer/Exchange and raml2html render the documentation in the order of

Anypoint

description:
type(json like)/examples
type detail

raml2html

description:
type detail
examples

The new notes? node should render at the end of these structures and behave the same way as the description node.

The documentation? node is not viable as that is only supported at the root of the RAML document.

Eric


#2

Hi Eric, thanks for you suggestion however I am not sure to understand neither the problem you are trying to solve nor the solution to that problem. Are you proposing a new facet notes? Is the ? (question mark) indicating that it would be optional? Where would that facet belong?


#3

Hi Jonathan,

The problem I am trying to solve is to add additional detailed contextual documentations at the URI level, so yes, an additional optional facet. I should have titled this [New Resource Property node facet : notes?]

Resources and Nested Resources

A resource is identified by its relative URI

Resource Property

The value of a resource node is a map whose key-value pairs are described in the following table.

It may also be appropriate for

Response Declaration

The value of a response declaration is a map that can contain any of the following key-value pairs:

An example of how this would be used would be for

responses:
  400:
    description: Bad Request. Invalid request syntax, the error message will in most cases contain the exact reason.
    **notes: !include list_of_all_possible_errors.md**        
    body:
      application/json:
        type: Error[]
        example: !include examples/400.error.raml

The real challenge I am having is this additional information is clearly documented in the back end systems that the interface is calling. Developers accessing the new interface should not have to go to the documentation for back end system (nor should we expose what that system is).

Eric


#4

This seems like a good fit for Annotations. Have you looked into that?

Developers accessing the new interface should not have to go to the documentation for back end system (nor should we expose what that system is)

You can define annotations in an Overlay document, this way those annotations are only visible when consuming the Overlay (not when consuming the API Spec document that the Overlay is extending).


#5

Yes, I haveā€¦but

Ultimately the goal is to use Anypoint Exchange as the mechanism to publish the documentation.
It would not recognize the annotations (speculation with a degree of confidence).


#6

I would raise this issue with the MuleSoft Anypoint Exchange team as this seems more like a feature request than a real need at the Spec level.