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

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 😉

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.

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

{  "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?