Forum Discussion

thor's avatar
thor
New Contributor
5 years ago
Solved

Url parameters in path and query

Hi there,

our api allows path parameters only.
Like so :

ourdomain.com/api/v1/param1/param2/param3/param4/


"param4" is subdivided in parameters. They serve more or less as
filters. Sub parameters may be "begin", "end", "format" and others.
"begin" and "end" are e.g. unixtimestamps "format" could be "xml".

ourdomain.com/api/v1/param1/param2/param3/begin-1560730667,format-json


So the "param4" are more or less query parameters. A similar implementation
with query parameters would be:


ourdomain.com/api/v1/param1/param2/param3/?begin=1560730667&format=json

So my prob is how to document our version. In our version param4 would be
single path parameter and therefore required. But it is of course not required.
So is there a way to document our version with swagger. That means to
describe param4 as not required or better describe the sub parameters.
If I declare param4 as "in query" of course it produces something like:


ourdomain.com/api/v1/{param1}/{param2}/{param3}/?param4=


which is not what I want.


Thanks a lot !

Best,

 

Thor

5 Replies

Sort By
  • HKosova's avatar
    HKosova
    Icon for Alumni rankAlumni
    5 years ago

    Hi Thor,

     

    describe param4 as not required

    In OpenAPI, path parameters are always required. If a path parameter is optional, you need to define two paths - with and without that parameter:

     

    paths:
  /api/v1/{param1}/{param2}/{param3}:
    ...
  /api/v1/{param1}/{param2}/{param3}/{param4}:
    ...

     

     

    "param4" is subdivided in parameters. They serve more or less as filters. Sub parameters may be "begin", "end", "format" and others.
    "begin" and "end" are e.g. unixtimestamps "format" could be "xml".

    ourdomain.com/api/v1/param1/param2/param3/begin-1560730667,format-json

    OpenAPI provides several serialization styles for path parameters, but there's no built-in style for dash-separated values inside a comma-separated list. The closest option is to define "param4" as a comma-separated array of strings and describe the possible prefixes and value format for each string:

     

    openapi: 3.0.0
paths:
  /api/v1/param1/param2/param3/{param4}:
    get:
      parameters:
        - in: path
          name: param4
          required: true
          description: >
            A list of filters. Each filter is in the format
            `prefix-value`. The supported prefixes are:

             * `begin` and `end` - the value is a Unix timestamp.
             * `format` - the value can be `json` or `xml`.
             * ..
          schema:
            type: array
            items:
              type: string
            minItems: 1
            example:
              - begin-1560730667
              - format-json

     

    • thor's avatar
      thor
      New Contributor
      5 years ago

      Hi Helen,

       

      that helped me a great deal!

      Thanks a lot!

       

      Similarly like you posted I used the parameters. In the editor it looks pretty good. Completely the way I wanted mit (please see attachment editorversion.PNG). Than I created html2 - client an put on my server. But than it looks differently (please see attachment readyclient.PNG).

       

      Sorry for this beginner question, but can you tell me, what has to be done in order to create a client / html-site, the looks the same way like the editor version ?

       

       

      Thanks a lot !

      Best,

       

      Thor

       

       

      • HKosova's avatar
        HKosova
        Icon for Alumni rankAlumni
        5 years ago

        Hi Thor,

         

        what has to be done in order to create a client / html-site, the looks the same way like the editor version ?

        The right-side panel of Swagger Editor is Swagger UI. To host Swagger UI on your server, use its dist assets and change the url parameter in index.html to point to your YAML/JSON file.