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.

        Gliffy Diagrams

          Attachments

            Issue Links

              Activity

                People

                Assignee:
                gayanw Gayan Weerakutti
                Reporter:
                pascal Pascal Brandt
                Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                  Dates

                  Created:
                  Updated:
                  Resolved: