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

Improve Resource Definition Documentation

    XMLWordPrintable

Details

    • Task
    • Status: Closed
    • Should
    • Resolution: Fixed
    • None
    • 2.21.0
    • None

    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

                gayanw Gayan W.
                pascal Pascal Brandt
                Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                  Created:
                  Updated:
                  Resolved: