Forum Discussion
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 😉
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 bodyResponse headerscache-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.
- chichepo2 years agoChampion 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
Related Content
- 5 years ago
- 2 years ago
Recent Discussions
- 5 days ago
- 24 days ago