Forum Discussion

thor's avatar
thor
New Contributor
5 years ago

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 paramet...
  • HKosova's avatar
    HKosova
    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.

HKosova's avatar
HKosova
SmartBear Alumni (Retired)

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
    SmartBear Alumni (Retired)
    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.

    • thor's avatar
      thor
      New Contributor
      5 years ago

      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

       

       

       

       

       

       

      • HKosova's avatar
        HKosova
        SmartBear Alumni (Retired)
        5 years ago
        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.