openapi

问题 What I'd like to do is specify that sometimes the response to an API call might be a PDF document, and sometimes it will be JSON. I'd like to do this in OpenAPI 3.0 format. In the case of a PDF, the response would look like this: responses: '200': description: An invoice in PDF format. content: application/pdf: schema: type: string format: binary And in the case of a JSON response, this would describe the response: responses: '200': description: A JSON object containing user name and avatar

问题 I get the response from an http request in the following form: it is an array of un-named array(s) and object(s). I cannot figure out the proper Swagger (Open API) specification for this case. [ [ { "prop1": "hello", "prop2": "hello again" }, { "prop1": "bye", "prop2": "bye again" } ], { "key": 123 } ] 回答1: The answer depends on which version of OpenAPI you use. OpenAPI 3.0 supports oneOf , so it's possible to define multiple schemas for array items: openapi: 3.0.0 ... paths: /something: get:

问题 I'm having trouble defining a reusable schema component using OpenAPI 3 which would allow for an array that contains multiple types. Each item type inherits from the same parent class but has specific child properties. This seems to work alright in the model view on SwaggerHub but the example view doesn't show the data correctly. TLDR; Is there a way to define an array containing different object types in OpenAPI 3? Response: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object

问题 I want to request a table from my database through my API. However, I don't know what number of columns the table will have, or what it will contain. How can I specify this in Swagger? This is what I would like to do: paths: /reports/{id}: get: summary: Detailed results description: filler parameters: - name: id in: path description: filler required: true type: integer format: int64 responses: 200: description: OK schema: type: array items: $ref: '#/definitions/DynamicObject' definitions:

问题 We're having trouble using the OpenAPI 2.0 discriminator in way that makes both the Swagger tools and the Jackson serializer happy. Problem: during serialization Jackson currently generates two JSON properties for the discriminator, one of them having a null value. OpenAPI 2.0 definition swagger: '2.0' info: version: v1 title: Error API paths: /errors: get: description: Stack Overflow test responses: '200': description: OK schema: $ref: '#/definitions/SpecificError' definitions: GeneralError:

问题 I'm writing an Open API 3.0 spec and trying to get response links to render in Swagger UI v 3.18.3. Example: openapi: 3.0.0 info: title: Test version: '1.0' tags: - name: Artifacts paths: /artifacts: post: tags: - Artifacts operationId: createArtifact requestBody: content: application/octet-stream: schema: type: string format: binary responses: 201: description: create headers: Location: schema: type: string format: uri example: /artifacts/100 content: application/json: schema: type: object

问题 In OpenAPI (Swagger) 2.0, we could define header parameters like so: paths: /post: post: parameters: - in: header name: X-username But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a way to define header parameters, which would further be used for authentication. What is the correct way to define request headers in OpenAPI 3.0.0? 回答1: In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema

问题 I'm using Cloud Endpoints Frameworks (2.0.1) for Java as part of my final year project and have been relatively successful with it so far. I don't have any problems when deploying to my appspot.com domain, however, I am running into some problems when deploying locally. (Any references to my-project-id in the following code blocks are aliases for my actual google cloud project id) I have a valid openapi descriptor (openapi.json) of an annotated @API class which I am deploying to cloud

问题 I want to combine an API specification written using the OpenAPI 3 spec, that is currently divided into multiple files that reference each other using $ref . How can I do that? 回答1: One way to do this is to use the open-source project speccy. Open the terminal and install speccy by running (requires Node.js): npm install speccy -g Then run: speccy resolve path/to/spec.yaml -o spec-output.yaml 回答2: Most OpenAPI tools can work with multi-file OpenAPI definitions and resolve $ref s dynamically.

问题 looks like official swagger for openapi specification V3 support is near release https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/, and the swagger-codegen has 3.0.0 support developed and passing some level of testing https://github.com/swagger-api/swagger-codegen on the 3.0.0 branch I have a swagger spec (generated from my existing 2.0 spec via https://github.com/mermade/swagger2openapi, output looks good) Is there an easy way to run the swagger-codegen without having to package