Search code examples
swaggerswagger-editor

Get information about the expected syntax of a string in the request body

I have been given a Swagger API with a request body defined as

{
  "SqlFilterList": "string",
  "SubjectKey": 0,
  "SubjectCwaListingKey": 0
}

The programmer who wrote the API is on vacation and can't be reached. I don't have access to the API code. Is there in general anyway to interrogate the api to determine what the valid values of "string" might be? Or do I have to wait for the person to come back to the office?

I have reviewed the API's documentation via its URL (which is why I know that it needs a string), I searched the Swagger website and I searched questions with tag [swagger] in stackoverflow and didn't spot anything.

If the answer is that I am out of luck (which I strongly suspect to be true) is there a way that I can suggest to the author to document the valid syntax of the "string" in the API so that the next person doesn't go through this?

Solution

  • It sounds like you have found your way to the Swagger-UI, displaying the API documentation and interactive "try it out" buttons.

    Most likely, the API is just not documented as thoroughly as you need it to be. But there's a chance you might be able to find more information from the Swagger spec. A couple of things you can do to dig deeper:

    Look at the Request Model

    In the Swagger-UI, click the "model" tab in the operation header:

    enter image description here

    This will display additional details about the request structure, if the developer has provided property-level descriptions. The misnamed "model schema" tab that displays by default is really an auto-generated example of the message structure; not so useful if you're looking for detailed request documentation.

    Inspect the Swagger Source

    You might be able to inspect the Swagger source specification that is populating the Swagger-UI. Try using the "view source" command in your browser, and look for the SwaggerUi object constructor. It will look something like this:

    var swaggerUi = new SwaggerUi({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  dom_id: 'swagger-ui-container'
});

    Follow the specified url to find the source Swagger spec, and see if there is any further information available. It's unlikely that you'll find more there than what's displayed in the Swagger-UI, but it's worth a shot.

    Note that there's another form of the SwaggerUi constructor that doesn't use a url property. Instead, it uses a spec property whose value is a (big!) JSON object. You can copy-paste that object into a Swagger or JSON editor (for easier reading with auto-format, syntax coloring, etc.) and see if there's any further info there.

    If the answer is that I am out of luck (which I strongly suspect to be true) is there a way that I can suggest to the author to document the valid syntax of the "string" in the API so that the next person doesn't go through this?

    Hopefully the API developer has provided a feedback channel, either through email or a support site. There might be some API documentation widgets that incorporate feedback or discussions directly, but Swagger-UI does not at this time, AFAIK.