What is a brief explanation of the OpenAPI?
I read the documentation, and watched some tutorials, but didn't get the idea
It is basically a documentation of APIs. We can add the url, response, body, params etc for all methods like GET, POST, PUT, DELETE etc and for all the responses 200, 500 etc.
Refer https://swagger.io/docs/specification/about/
Related
For post and put methods, this can be done using requestBody, but i have filters and want to add some examples.
{{url}}/api/method?filter[qweqwe]=Test
In SpringDoc, you can use #Parameter to add descriptions and additional information for a query parameter. However, there doesn't appear to be a straightforward way to do it for parameters within a request body, especially for POST and PUT requests.
Is there a way to do this via annotations or is this a non-supported feature?
Apply #Schema to your request body object in the individual fields.
While designing a GET endpoint I am confused ...
Have designed Open API spec 3.0 for successful response ( 200 ) , invalid request ( missing mandatory stuff ) ( 400 )
Now I am confused about things like : 401 ( Unauthorized ) , 405 ( Method not allowed ) , 415 ( Unsupported Media type )
This API will need an api key to be provided in header and if not provided by user or an invalid api key is provided then they should get a 401
So I think I should be specifying 401 in my response spec .
However when I look at swagger's Pet store ( https://editor.swagger.io/ ) they are not having this response code anywhere ... ?
My API spec ONLY supports GET with Content-type : application/json so I am thinking we dont need 405 ( DELETE / POST / PUT etc ) .
Similarly if consumer sends application/xml or anything other than application/json we are not supporting it so this is why we should not be explicitly defining 415 in the spec ?
A bit confused which is why am looking into some inputs.
Was referring to some pages here and here
I think it is a good idea to document the Response Codes the API might return, it is indeed supported (but optional) by OpenAPI.
The consumers might find useful to know 401 Unauthorized means the JWT token is not supplied or it is expired, or 400 means the payload is incorrect (i.e. missing a specific attribute).
Check this example if you would like to see how Response Codes are documented and displayed by Swagger UI.
However when I look at swagger's Pet store they are not having this response code anywhere ... ?
The Pet Store is really just an example that one can use as a starting point or when you want to feed a tool with a sample spec. It is not meant to be normative. If you look through the sample code, you will even find paths which are RPC style (e.g. here) and other things that are not exactly RESTful.
why we should not be explicitly defining 415 in the spec ?
I think the blogposts that you found are helpful and do not contradict each other. Both of them rightfully recommend you to use the standard http response codes and provide a helpful error body. Some people omit response codes that they think are self-explanatory. But IMO, adding these few lines is totally worth it. If you add them diligently, then you get a key aspect of openapi right: The purpose of openapi is clarity and predictability of the capabilities and behaviour of your API.
So in summary: Yes, think about the responses that you are going to need, and do include these response codes in your api spec.
I am using swagger openapi specification 3.0 to generate swagger from my interface. I have a delete method where it accepts request-body. But according to RFC7231, DELETE does not accept any request body. Also Swagger-request body tells that so. But my API is designed to accept request body in DELETE operation. Is there any work around in creating swagger such that DELETE operation accepts request body. Currently what error I am getting from swagger generation is,
Sematic error: DELETE operations cannot have a requestBody
No, you cannot use the OpenAPI 3.0 Specification and Swagger tools to implement DELETE requests with a request body. As you correctly pointed out, the HTTP RFC says the DELETE request body has no defined semantics (and thus should be avoided), and OpenAPI 3.0 specifically disallows bodies in HTTP methods where the body does not have defined semantics. See this discussion for some context.
Consider changing your API design, for example, replace the DELETE body with path, query string or header parameters. Check out RESTful Alternatives to DELETE Request Body for some ideas.
This type of operation (DELETE, GET requests with a body) was explicitly banned in Open API 3.0. Prior to that it was allowed or vague.
I'm writing a RESTful service using odata4j and need to be able to set the caching header of the response.
How do I do this?
I don't seem to have access to the HttpservletResponse object.
And unlike the JAX-RS support, I can't see anything in odata4j that lets me get hold of a CacheControl object.
Thanks
Sarah
No direct support for this as of 0.5 - however you could write a custom ContainerResponseFilter to modify the outgoing response manually.
Feel free to add a feature request on the project issue list [1], along with any detail on a proposed api if you have thoughts on how this might work.
Or, of course, a patch... : )
Hope that helps,
- john
[1] http://code.google.com/p/odata4j/issues/list