Uploaded image for project: 'Webservices REST Module'
  1. Webservices REST Module
  2. RESTWS-562

Improve Resource Definition Documentation

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: Should
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.21.0
    • Complexity:
      Low

      Description

      Right now, we we only document full representations and have completely separate definitions in the Swagger spec for GET and POST objects. Also, all datatypes are string. We should improve things by using better schema objects that include the correct data type.

      Having some examples in the docs also wouldn't hurt.

      Approach taken to implement as discussed in the talk thread:

      • Use swagger-core library as a helper library. This prevents us from having to maintain our own set of swagger model classes.
      • Introuduces three new methods, which are used to document resource classes.
        • getGETModel(Representation) : returns a object representing GET representation schema of the resource
        • getCREATEModel(Representation) : returns a object representing CREATE representation schema of the resource
        • getUPDATEModel(Representation) : returns a object representing POST Update representation schema of the resource

      A resource should implement these methods in order for it to be appear on the swagger doc, though it is not mandatory.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              gayanw Gayan Weerakutti [X] (Inactive)
              Reporter:
              pascal Pascal Brandt
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: