cancel
Showing results for 
Search instead for 
Did you mean: 

Url parameters in path and query

SOLVED
Highlighted
New Contributor

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

1 ACCEPTED SOLUTION

Accepted Solutions
Highlighted
Moderator

Re: Url parameters in path and query

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

5 REPLIES 5
Highlighted
Moderator

Re: Url parameters in path and query

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

 


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Highlighted
New Contributor

Re: Url parameters in path and query

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).editorversion.PNG Than I created html2 - client an put on my server. But than it looks differently (please see attachment readyclient.PNG).

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

 

 

Highlighted
Moderator

Re: Url parameters in path and query

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

Highlighted
New Contributor

Re: Url parameters in path and query

Hi Helena,

 

again ... that worked very well.

Thanks a lot!

 

non-the-less I have another question with regard to the layout.... would be grateful if you can get me started one more time.

 

Before I just created an html2-client. It looked a bit different to the right (display-) side of the swagger editor but it had a vertical menu on the left side.

 

Now I followed your instruction a delivered 100 % of what I had asked for, but is there a way to a navigation bar ? Can you tell how to get that ?

 

Best Thanks!

 

Thor

 

 

 

 

 

 

Highlighted
Moderator

Re: Url parameters in path and query


is there a way to a navigation bar ?

Swagger UI does not have a built-in navigation bar, this is something you'll need to add yourself. Here's an example of how someone else did it:

https://api.biostar2.com/v2/docs/

 

Basically, instead of using Swagger UI's index.html page you can create your own web page with a navigation bar and embed the Swagger UI component into the page. Swagger UI generates anchors (aka deep links) for individual tags and operations:

PAGE_URL#/tagName/operationId

You can include these links in your navigation bar to scroll to specific tags and operations.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
New Here?
Join us and watch the welcome video:
Top Kudoed Authors