Forum Discussion

pathaniaamn's avatar
pathaniaamn
New Contributor
2 years ago

API specification | URI Versioning, security with api key/secret and Okta/Auth0, forming request/res

I am first time user of Swagger and have very rookie questions but as I could not find the answers anywhere, I believe this would help to document this for clarity to new users in future as well.

 

I am working on a new project for which there is code base yet and I would like to create a API documentation in such a way that it could be used once project is established as well -

1. How can demonstrate URI based versioning? (remember there is no code base for this project yet. I am building a skeleton of the design that could be an input for developers to build their BE services)

2. authentication - how are these endpoints authenticated? Do i have to bind an okta service to make it work? or can i use something as dummy authentication to make it work?

3.  One thing I noticed is that every request and response would be different. Does that mean for every verb (GET, POST) with endpoint, I would have to create two schemas - one for request and other for response. I was not able to reuse the schema and thats where my problem is.

6 Replies

  • chichepo's avatar
    chichepo
    Champion Level 2

    Hi pathaniaamn 

    I'll try to give you some very first answers.


    1. How can demonstrate URI based versioning? (remember there is no code base for this project yet. I am building a skeleton of the design that could be an input for developers to build their BE services)

    Service URI versionning is usually using a clear definition of the base path and the endpoint path.
    The backward compatibility, is ensured by version incrementation of the base path, for example :

     


    2. authentication - how are these endpoints authenticated? Do i have to bind an okta service to make it work? or can i use something as dummy authentication to make it work?

    SwaggerHub is supporting all kind of "most used" authentication methods.
    Even if you are using Okta, you should be able to define the authentication accordingly.
    Authentication methods can be applied to the whole Swagger file or/and to a specific endpoint.
    I invite you to have a look on the admin guide here


    3.  One thing I noticed is that every request and response would be different. Does that mean for every verb (GET, POST) with endpoint, I would have to create two schemas - one for request and other for response. I was not able to reuse the schema and thats where my problem is.

    The endpoint part (Path) include all your endpoints and methods definitions.
    The data model part (Schemas) describe your objects and properties.
    Of course, you can imagine to reuse objects and properties according to your business specifications.

     

    In addition, when using OAS 3, very useful properties like allOf, oneOf and anyOf can be used for polymorphism coding.
    In such way you can imagine a lot of reusability combinations.

    I hope it's a good beginning for answering your questions.
    Let us know ğŸ˜‰


    • pathaniaamn's avatar
      pathaniaamn
      New Contributor

      Thanks chichepo This was very helpful. Here is an update -

       

      1. Versioning resolved. all set there.

       

      2. Regarding authentication - I don't have Okta to be tied to it. Can i use something to behave like dummy authentication? I just want to make sure my request and responses work. Currently, I have defined request and responses in swagger but unable to feature "try it out" as I get an error  

       

      Error: response status is 404

      Response body
      Response headers
       cache-control: no-cache  content-length: 0  content-type: application/octet-stream  date: Thu,16 Mar 2023 16:49:16 GMT  etag: W/"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk"  expires: -1  status: 404 Not Found 

       

      Related issues with #2:  I have defined my request and response for application/json but I see

      content-type: application/octet-stream in response when I execute the endpoint.

       

      Here is my configuration:

      paths:
      /portfolios:
      post:
      tags:
      - portfolio
      summary: create a new portfolio
      description: >-
      This endpoint creates a new portfolio in the system with its unique name and enumeration.
      operationId: addPortfolio
      requestBody:
      description: Create a new portfolio in the system.
      content:
      application/json:
      schema:
      $ref: '#/components/schemas/create-portfolio'
      required: true
      responses:
      '200':
      description: Portfolio created successfully.
      content:
      application/json:
      schema:
      $ref: '#/components/schemas/portfolio-created'

       

      Your quick response is much appreciated.

       

      • chichepo's avatar
        chichepo
        Champion Level 2

        pathaniaamn 
        You can define a dummy authenticaton.

         

        Try the simplest one: apiKey 

         

        Regarding the issue in the response content type, it depends on the server application.
        You can, of course, change your API specification with content-type: application/octet-stream if it makes sense in term of behavior expectation.
        If not, you should ask your backend app developper to modify the output payload content format to Json

         

  • pathaniaamn's avatar
    pathaniaamn
    New Contributor

    Update:

    1. Versioning resolved. all set there. How I fixed it. Here is the sample yaml :

    openapi: 3.0.0
    servers:
    # Added by API Auto Mocking Plugin
    - description: SwaggerHub API for Aman
    url: https://virtserver.swaggerhub.com/aman/1.0.0

    This will ensure versioning is applied for all endpoints.

     

    2. Regarding authentication  - Able to configure API Mocking. All set here as well. So, I am seeing responses with HTTP 200 (Refer to this link for more information - https://support.smartbear.com/swaggerhub/docs/integrations/api-auto-mocking.html)

     

    Now, I am working on getting on how to get request headers and response headers for my APIs. Please message here if you have any information on that.

     

  • pathaniaamn's avatar
    pathaniaamn
    New Contributor

    Update:

    Authentication worked using apiKey as well.

     

    Though, I am stuck in a weird issue. I am preparing a GET request and getting an error as below. Based on the error, request header should be declared.

     

    So, I want to declare request header as application/json  but I am not able to as it is not supported in  openapi: 3.0.0

     

    415
    Undocumented

    Error: response status is 415

    Response body
    Download
     
    {  "message": "Request validation can only interpret application/json bodies. You must provide \"Content-Type: application/json\" in the request headers."
    }

     

    It was supported in openapi: 2.0.0 as mentioned in the link below. 

    https://swagger.io/docs/specification/2-0/mime-types/

     

    and in openapi: 3.0.0 there is nothing mentioned how to handle this for a GET request as all examples state information for responses.

    https://swagger.io/docs/specification/media-types/

     

    Did anyone face issue like this?

    • chichepo's avatar
      chichepo
      Champion Level 2

      pathaniaamn 
      Look at this post. It may help you.
      There is no answer there but, when looking at the structure #2, you should understand the way it should be sent.