twskj/pretty-swag

Feature request: generate examples in output

Closed this issue · 12 comments

aaime commented

Looks like example outputs are not generated, e.g.:

---
swagger: '2.0'
info:
  version: 1.0.0
  title: OpenSearch for EO search index access
  description: Allows to manipulate the OpenSearch for EO index
host: localhost:8080
basePath: /geoserver/rest/oseo/

paths:
  /collections:
    get:
      description: Retrieves a list of all available collections (nakes and links)
      parameters:
        - name: offset
          in: query
          description: First element for paged responses
          required: false
          type: integer
        - name: limit
          in: query
          description: Number of elements in page
          required: false
          type: integer
      produces:
        - application/json
        - application/xml
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "collections" : [
                      {
                        "name" : "SENTINEL1",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL1.json"
                      },
                      {
                        "name" : "SENTINEL2",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL2.json"
                      }
                  ]
              }

Does not contain the examples section for the 200 response.

twskj commented

I don't have Examples section in yet. But should be relatively easy to put in. I'll add it in soon.

twskj commented

Rolled out. Check it out and let me know.

twskj commented

To me, design wise, it doesn't "flow" like I want it to be. But I couldn't come up with a better design for now. Feel free to suggest alternative layout/wording.

aaime commented

Hi, thank you for the quick turn around!
The output seems nice, however the json is not quite readable, \n is replacing newlines making the JSON hard to read. Is there a way to change my input file to avoid it?

selezione_261

twskj commented

Let me check. I didn't see it on my test case.

twskj commented

I just checked. If you describe your example in object format, it would work with the current version.
But I'll add an auto-conversion for you too :-)

Here's an example of working yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: OpenSearch for EO search index access
  description: Allows to manipulate the OpenSearch for EO index
host: 'localhost:8080'
basePath: /geoserver/rest/oseo/
paths:
  /collections:
    get:
      description: Retrieves a list of all available collections (nakes and links)
      parameters:
        - name: offset
          in: query
          description: First element for paged responses
          required: false
          type: integer
        - name: limit
          in: query
          description: Number of elements in page
          required: false
          type: integer
      produces:
        - application/json
        - application/xml
      responses:
        '200':
          description: Success
          examples:
            application/json:
              collections:
                - name: SENTINEL1
                  href: http://host:port/geoserver/rest/oseo/collections/SENTINEL1.json
                - name: SENTINEL2
                  href: http://host:port/geoserver/rest/oseo/collections/SENTINEL2.json
twskj commented

I rolled out an updated version. You should be able to pass in either string or object.
Test it out and let me know.

aaime commented

Yep, works, thanks a lot!

twskj commented

I'm revisiting this issue. What do you think of this new design here:

image

aaime commented

Sure, that works too :-)

twskj commented

Thanks for your feedback.

twskj commented

Rolled out on: 0.1.114