openapi

问题 I am familiar with the Microsoft stack. I am using OData for some of my restful services. Recently I came across Swagger for API documentation and I am trying to understand how it relates to OData. Both of them seem to be RESTful specifications. Which one is widely used? 回答1: Swagger is a specification for documenting APIs . By creating a swagger document for your API, you can pass it to an instance of Swagger UI, which renders the document in a neat, readable format and provides tooling to

问题 I have a class that one of the properties can be string or array of strings, not sure how should I define it in swagger @ApiProperty({ description: `to email address`, type: ???, <- what should be here? required: true, }) to: string | Array<string>; update As @Youba suggeted answer I tried @ApiProperty({ description: `to email address(es)`, additionalProperties: { oneOf: [ { type: 'string' }, { type: 'Array<string>' }, ], }, required: true, }) and @ApiProperty({ description: `to email address

问题 I have a class that one of the properties can be string or array of strings, not sure how should I define it in swagger @ApiProperty({ description: `to email address`, type: ???, <- what should be here? required: true, }) to: string | Array<string>; update As @Youba suggeted answer I tried @ApiProperty({ description: `to email address(es)`, additionalProperties: { oneOf: [ { type: 'string' }, { type: 'Array<string>' }, ], }, required: true, }) and @ApiProperty({ description: `to email address

问题 I am having a problem with setting up the swagger into my node.js application. I am using swagger-jsdoc and swagger-ui-express for creating documentation. Here are the versions "swagger-jsdoc": "3.5.0", "swagger-ui-express": "4.1.3" Below is the configs, which I pass to swagger-jsdoc. openapi: 3.0.0 info: description: test version: 3.0.0 title: U-CRM api documentation termsOfService: http://swagger.io/terms/ servers: - url: 'https://localhost:5000' description: Local server tags: - name: U

问题 For a web application I am working on, I need to fetch some binary (meta) data for an audio file. This is how the endpoint looks like: @RequestMapping( value = "/tracks/{trackId}/metadata", method = RequestMethod.GET, produces = MediaType.APPLICATION_OCTET_STREAM_VALUE ) @ApiResponse( description = "Successful Operation", responseCode = "200", content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE) ) public StreamingResponseBody getTrackMetadata(@PathVariable("trackId") Long

问题 I'm having difficulty understanding the correct way to include validation information in a swagger file, when the validation logic can be dynamic (default, minValue, maxValue, etc.). Consider the following example: In a banking application, we a have a REST API for withdrawals. The withdrawal amount cannot be greater than the account value of the person taking the withdrawal. This value is going to depend on the context (Who's bank account we are withdrawing from) to get that maximum value.

问题 I'm having difficulty understanding the correct way to include validation information in a swagger file, when the validation logic can be dynamic (default, minValue, maxValue, etc.). Consider the following example: In a banking application, we a have a REST API for withdrawals. The withdrawal amount cannot be greater than the account value of the person taking the withdrawal. This value is going to depend on the context (Who's bank account we are withdrawing from) to get that maximum value.

问题 I'm having difficulty understanding the correct way to include validation information in a swagger file, when the validation logic can be dynamic (default, minValue, maxValue, etc.). Consider the following example: In a banking application, we a have a REST API for withdrawals. The withdrawal amount cannot be greater than the account value of the person taking the withdrawal. This value is going to depend on the context (Who's bank account we are withdrawing from) to get that maximum value.

问题 Here it says I could refer to the definition in another file for an individual path, but the example seems to refer to a whole file, instead of a single path definition under the paths object. How to assign an individual path in another file's paths object? For example, I have Anotherfile.yaml that contains the /a/b path: paths: /a/b: post: In another file, I use $ref to reference the /a/b path as follows: paths: /c/d: $ref: 'Anotherfile.yaml#/paths/a/b' but this gives an error: Could not

问题 I'm trying to achieve an OpenAPI definition where I define a shared, complete list of allowed values as an enum and then use subgroups of the values in different places to show which values are allowed in each case. Using the example from the enum spec on Swagger.io, if I have a definition like this: paths: /products: get: parameters: - in: query name: color required: true schema: $ref: '#/components/schemas/Color' responses: '200': description: OK components: schemas: Color: type: string