openapi

问题 I want almost all my paths to have the following 3 generic error responses. How do I describe that in Swagger without copypasting these lines everywhere? 401: description: The requester is unauthorized. schema: $ref: '#/definitions/Error' 500: description: "Something went wrong. It's server's fault." schema: $ref: '#/definitions/Error' 503: description: Server is unavailable. Maybe there is maintenance? schema: $ref: '#/definitions/Error' Example of how I use this in a request: paths: /roles:

问题 PROBLEM STATEMENT: For a "strange" reason, all our operations of an API have different "host". We have API like this: operation 1: GET https://host1:port1/api/resources operation 2: GET https://host1:port2/api/resources/{id} operation 3: POST https://host2:port3/api/resources operation 4: POST https://host2:port4/api/resources/search If we use Swagger/OpenAPI as it is, it means creating one Swagger/OpenAPI specification per operation, resulting having one swagger-ui page per operation, and

问题 I am trying to document with OpenAPI a query string which look like filtered[0][id]=code&filtered[0][value]=12345 and contains a list of object with properties id and value . My yaml documentation looks like the following parameters: - name: filtered in: query description: filters to be applied explode: true style: deepObject schema: type: array items: properties: id: description: name of the field to be filtered type: string value: description: value of the filter type: object The problem is

问题 Due to some backward compatibility reasons, I need to support both the paths /ab and /a-b . The request and response objects are going to be the same for both of the paths. Can I have something like the following in my Swagger spec so that I do not have to repeat the request and response object definitions for both the paths. paths: /ab: /a-b: post: ... 回答1: Yes, you can have a path item reference another path item, like this: paths: /ab: ... /a-b: $ref: '#/paths/~1ab' Here, ~1ab is an

问题 Referencing OpenAPI 2.0, Schema Object, or Swagger 2.0, Schema Object, and the definition of discriminator field as: Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it. My confusions/ questions: It is ambiguous

问题 The API I'm trying to describe has a structure where the root object can contain an arbitrary number of child objects (properties that are themselves objects). The "key", or property in the root object, is the unique identifier of the child object, and the value is the rest of the child object's data. { "child1": { ... bunch of stuff ... }, "child2": { ... bunch of stuff ... }, ... } This could similarly be modeled as an array, e.g.: [ { "id": "child1", ... bunch of stuff ... }, { "id":

问题 I have a path that uses complex models with almost identical properties for each http method. The problem is that I want to define some required properties for the request of PUT and POST, while no properties are required in GET response (as the server always returns all properties and it's mentioned elsewhere in the documentation). I created a simple cat API to demonstrate what I've tried. The idea is that for GET response the response model doesn't have anything marked as required, but the

问题 I'm trying to setup a NodeJS REST API using Google Cloud Endpoints and Google App Engine. I've cloned the offical sample project from GitHub and set up Google Cloud Endpoints using the Quickstart. Out of the box, it works fine,but I tried adding another API endpoint for a GET request at / , but the response I get after I deploy and make the request is as follows: { "code": 5, "message": "Method does not exist.", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "stackEntries

问题 I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters. Example: <baseURL>/path can use ?filter1= or ?filter2= , and these parameters should produce different response messages. I want my OpenAPI YAML file to document these two query params separately. Is this possible? 回答1: It is not supported in the 2.0 spec, and not in 3.0 either. Here are the corresponding proposals in the OpenAPI Specification repository: Accommodate legacy APIs

问题 I'm trying to deploy a simple endpoint which contains a parameter of type file . I'm using the gcloud service-management deploy command with the following openapi compliant yaml: swagger: "2.0" info: description: "Image API" title: "Image API" version: "v1" host: "image-api.endpoints.myproject.cloud.goog" basePath: "/v1" schemes: - "https" paths: "/images": post: description: "Adds an image" operationId: "add" consumes: - "multipart/form-data" produces: - "application/json" responses: 201: