Spec'ing an endpoint that returns different responses depending on params sent
I am new to openapi and am evaluating it in order to spec a REST API characterized by endpoints that return different(ly structured) responses depending on which query parameters are sent to the server. I have been tasked with extending one such API (not written by myself). For example, let's say an endpoint www.acme.com/gizmo supports 6 query parameters param1, param2, ..., param6. If the odd-numbered params (param1, param3, param5) are initialized the server responds with the XML message <foo>...</foo>. However if the even-numbered params (param2, param4, param6) are initialized the server responds with the XML message <bar>...</bar> etc. Frankly, I don't think this is a good design (or is it?) but the API has been shipped and customers are using it. What I'd like to know if whether openapi can be used to spec such an endpoint.Solved1.1KViews0likes3CommentsSwagger multiple definitions best practices
I posted this same question to Stack Overflow but it didn't get any attention: https://stackoverflow.com/questions/64790650/swagger-multiple-definitions-best-practices I have an API, and a consumer web app, both written in Node and Express. The API is defined by a OpenAPI Specification. Implemented by swagger-ui-express[1]. The above web apps are Dockerised and managed in Kubernetes. The API has a handful of endpoints for managing the lifecycle of a user's registration/application to the service. Currently, when I need to cleardown completed/abandoned applications, or resubmit failed applications, I employ a periodically run cronjob to carry out a database query for the actions mentioned. The cronjob is defined by a Kubernetes config YAML file. This is quickly becoming unmanageable, and hard to maintain. I am looking in to having a dedicated endpoint for each of the above tasks. Then a dedicated cronjob could periodically send a request to the API endpoint to carry out the complex task. This moves the business logic back in to the API, and avoids duplication within a cronjob hosted elsewhere. I am ultimately asking if this is a good approach or is there a better workflow documented somewhere I could implement? My thinking is that I could add these new endpoints to the already-existing consumer API, but have the new (housekeeping/management) endpoints separated from the others. To separate each (current) endpoint in to their respective resource, I am defining tags within the specification. Tags don't seem to be sufficient for the separation of these new "housekeeping" endpoints. Looking through the SwaggerUI documentation[2] I can see that I can define multiple definitions (via the `urls` property) to switch between. These definitions being powered by individual Specification documents. This looks like a very clean way of separating the consumer API from the admin API, is this best practice? Any input would be appreciated on this as I am struggling to find much documentation on this kind of issue. [1]: https://www.npmjs.com/package/swagger-ui-express [2]: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.mdObject property name as UUID
In the given API response how would you write the schema yaml to support UUIDs as a property name { "results": { "11b17cd8-0000-0000-0000-2092b242027f": [ { "id": "0000", "type": "Home", "ownership": "", "monthly": "0", "address_1": "23299 Address Parts", "address_2": "", "city": "Some City", "state": "ZZ", "zip": "00000", "active": "1", "primary": "1" } ] } } Here is my attempt (schema portion): components: schemas: uuid: type: string format: uuid description: UUID example: 00000000-0000-0000-0000-000000000000 pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' CustomerAddresses: type: object properties: '#/components/schemas/uuid': type: array items: $ref: '#/components/schemas/CustomerAddress' CustomerAddress: type: object properties: id: type: string example: "3014" type: type: string enum: ['Home', 'Work'] ownership: type: string example: "" monthly: type: string example: "0" address_1: type: string example: "23444 Address Parts" address_2: type: string example: "Unit 42" city: type: string example: "Some City" state: type: string maxLength: 2 minLength: 2 example: "ZZ" zip: type: string format: int32 example: "00000" active: type: string enum: ["0", "1"] primary: type: string enum: ["0", "1"]SolvedChanging API Response Based on Query Parameter
Hi all, I'm trying to figure out if it's possible to specify different API behaviors for a single endpoint with the Swagger editor based on query parameter provided? I'm looking at and endpoint like this: /processes/{processId}?detail={detailLevel} where {processId} is an integer and {detailLevel} is a string enum between "summary" and "robust". The robust response would look something like this robustResponse = { "name": "mt-olympus" "macAddress": "ABC123", "status": unreachable, "timezone": "America/New_York", "osName": "Microsoft FooBar", "osVersion": "6.1.2", } And the summary response would look more like this: simpleResponse = { "name": "mt-olympus", "statusColor": "red" } What I would like to do is specify two types of response objects, and return them based on query parameter of the request. I don't want to use different API endpoints, because both of these responses are querying the same source of data. My question is: how do I define API responses that change based on query parameters in the Swagger editor (or in an openAPI spec generally?) Alternatively, this may be an XY question. Should I just write 2 separate API endpoints to handle this?Solved1.4KViews0likes2CommentsAdd Upload button for OpenAPI 2.0 file as Octet-Stream
Context I am using OpenAPI ver 2.0 I have API which consumesapplication/octet-stream(JavaInputStream) Issue In OpenAPI ver 2.0 I can only set input type asmultipart/form-data(link) to have upload button. When I have applied this solution for my swagger: <code> "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "in": "formData", "name": "messageFile", "description": "Description...", "required": true, "type": "file" } ] </code> I am getting following error:Unsupported Media Typeafter sending a file - itis normal due to my API wants octet-stream. Question Is it possible to have upload button using OpenAPI ver 2.0 andapplication/octet-streamlike: If no, then what will be better solution / workaround for this?Solved3.5KViews0likes3Commentsgenerate server for Java 7
Hi, I have a yaml file loaded in editor.swagger.io and from there, I have generated the server code for jaxrs-resteasy. The problem is this code must be integrated in a Java 7 project and Swagger generates the code for Java 8. Is there any way to generate in Swagger the code for Java 7?Swagger Core 2.x OpeanAPI 3 Examples tied to Dataclass(variables)
I'd like to to add examples to my OpenAPI 3 Autogenerated Documentation which I generate with "io.swagger.core.v3.swagger-gradle-plugin" I didn't find a way to bind the example to the variable of my dataclass, like you could do with @ApiModelProperty for a swagger V2 file. All I found is @ExampleObject which you have to define for each response as a String. Am I missing something or is that the only way to add Examples to a swagger.v3 approach?Which library to use to implement OpenAPI
hello, I'm going to implement many new web microservices. I'm discovering OpenAPI (YAML/JSON Schema), and and I'm enthusiastic about it. But I'm lost in the existing libraries implementing it. I would like to use Python and I'm familar with flask; but then... what do you think of: connexion: https://github.com/zalando/connexion flasgger: https://github.com/flasgger/flasgger swagger-ui: https://pypi.org/project/swagger-ui-py flask-swagger-ui: https://pypi.org/project/flask-swagger-ui flask-restplus: https://flask-restplus.readthedocs.io/en/stable flask-rest-api: https://flask-rest-api.readthedocs.io/en/stable flask-restful: https://flask-restful.readthedocs.io/en/latest/ can you guide me to use the right promising libraries, with large communities. Many thanks. GuillaumeCan Swagger UI for Openapi v3 handle arrays in multipart requests?
I have the following Openapi document: { "info": { "description": "This document shows strange behavior in swagger ui", "title": "This document shows a strange behavior in swagger ui", "version": "0.0.0" }, "openapi": "3.0.0", "paths": { "/post": { "post": { "description": "Upload multiple files", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "inputResources": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Multipart body to upload files" } } }, }, "servers": [ { "url": "https://httpbin.org" } ] } I want to display it with Swagger UI so I created the following HTML page: <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script> <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js"> </script> <script> window.onload = function() { const ui = SwaggerUIBundle({ url: "path/to/above/document", validatorUrl : null, dom_id: '#swagger-ui', deepLinking: true, }) window.ui = ui } </script> <div id="swagger-ui"></div> I get a nice display of my request However when I execute it the following multipart body is sent: ------WebKitFormBoundaryzRaOvYA1aX8T4BXu Content-Disposition: form-data; name="inputResources" ewrr,eeee ------WebKitFormBoundaryzRaOvYA1aX8T4BXu-- As you see the strings are just comma-separated which is not a valid way to encode an array of strings in a multipart body. I would expect a part for each string element to be created like that: ------WebKitFormBoundaryzRaOvYA1aX8T4BXu Content-Disposition: form-data; name="inputResources" ewrr ------WebKitFormBoundaryzRaOvYA1aX8T4BXu Content-Disposition: form-data; name="inputResources" eeee ------WebKitFormBoundaryzRaOvYA1aX8T4BXu-- Even worse when I change the format of the inputResources property to binary to send files instead. "inputResources": { "items": { "format": "binary", "type": "string" }, "type": "array" } This changes the multipart body to the following: ------WebKitFormBoundary5OvyKi6BDAuPKnFm Content-Disposition: form-data; name="inputResources" [object File],[object File] ------WebKitFormBoundary5OvyKi6BDAuPKnFm-- Again I would have expected two parts with the respective file's binary content. Am I assuming correctly that Swagger UI simply does not support arrays yet in multipart request bodies? Or did I do something wrong? Kind regards, Neidharttags not generated in YAML file using swagger-maven-plugin
Hello, I am using swagger-maven-plugin to generate a YAML file based on openAPI annotations. https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin The issue is that tags are not generated. I am using org.eclipse.microprofile.openapi.annotations.tags Any suggestions on how I can solve this issue: what I need to change in the pom.xml file? My pom.xml looks like this: <plugin> <groupId>io.swagger.core.v3</groupId> <artifactId>swagger-maven-plugin</artifactId> <version>2.0.8</version> <configuration> <openapiFilePath>${project.basedir} --this is a PATH to my configuration.yaml file</openapiFilePath> <outputFileName>result</outputFileName> <outputFormat>JSONANDYAML</outputFormat> <outputPath>${project.build.directory}</outputPath> <prettyPrint>true</prettyPrint> </configuration> <executions> <execution> <phase>compile</phase> <goals> <goal>resolve</goal> </goals> </execution> </executions> </plugin> Thanks a lot, BogdanSolved3.8KViews0likes2Comments