openapi | 易学教程

How to define UUID property in JSON Schema and Open API (OAS)

阅读更多关于 How to define UUID property in JSON Schema and Open API (OAS)

When using JSON Schema and Open API specification (OAS) to document a REST API, how do I define the UUID property? There's no built-in type for UUID, but the OpenAPI Specification suggests using type: string format: uuid From the Data Types section (emphasis mine): Primitives have an optional modifier property: format . OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email" , "uuid" , and so on, MAY be used even though

What is the 'scopes' field of the swagger security scheme object used for?

阅读更多关于 What is the 'scopes' field of the swagger security scheme object used for?

问题 petstore_auth: type: oauth2 authorizationUrl: http://swagger.io/api/oauth/dialog flow: implicit scopes: write:pets: modify pets in your account read:pets: read your pets This is a securityDefinitions example from the Swagger Specification. What does the write:pets and read:ptes intended for? Is that some categories for the paths? 回答1: write:pets and read:pets are Oauth2 scopes and are not related to OpenAPI (fka. Swagger) operations categorization . Oauth2 scopes When an API is secured with

BeanConfig (or similar?) in Swagger 2.0 (OpenApi 3.0)

阅读更多关于 BeanConfig (or similar?) in Swagger 2.0 (OpenApi 3.0)

I am currently migrating our API docs (which were Swagger 1.5) to Swagger 2.0 (OpenApi 3.0) The API docs are Swagger docs which get generated with java annotations using maven packages swagger-annotations and swagger-jaxrs . I have already updated the pom.xml with new versions so it looks like: <dependency> <groupId>io.swagger.core.v3</groupId> <artifactId>swagger-annotations</artifactId> <version>2.0.6</version> </dependency> <dependency> <groupId>io.swagger.core.v3</groupId> <artifactId>swagger-jaxrs2</artifactId> <version>2.0.6</version> </dependency> And also all the old annotations are

How do I combine multiple OpenAPI 3 specification files together?

阅读更多关于 How do I combine multiple OpenAPI 3 specification files together?

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? 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 Most OpenAPI tools can work with multi-file OpenAPI definitions and resolve $ref s dynamically. If you specifically need to get a single resolved file, Swagger Codegen can do this. Use Codegen 3.x with

How to keep the single resource representation approach using OpenAPI spec

阅读更多关于 How to keep the single resource representation approach using OpenAPI spec

问题 Reading this post (see: 3 How to use a single definition when... ) about describing a REST API using OpenAPI (Swagger) specification you can note how to keep a single resource representation for adding/updating and getting resource using readOnly property instead of having one representation for getting (GET a collection item) and other one for adding (POST to a collection). For example, in the following User single representation, the id is a read-only property which mean that it won't be

How to define parameters with square brackets in OpenAPI (Swagger)?

阅读更多关于 How to define parameters with square brackets in OpenAPI (Swagger)?

I have an endpoint with query parameters that use square brackets: GET /info?sort[name]=1&sort[age]=-1 Here, name and age are the field names from my model definition. How can I write an OpenAPI (Swagger) definition for these parameters? It depends on which version of OpenAPI (Swagger) you use. OpenAPI 3.0 The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject and explode: true . openapi: 3.0.0 ... paths: /info: get: parameters: - in: query name: sort schema: type: object properties: name: type: integer

com.google.api.config.ServiceConfigSupplier - Failed to fetch default config version for service (only on localhost)

阅读更多关于 com.google.api.config.ServiceConfigSupplier - Failed to fetch default config version for service (only on localhost)

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 endpoints using "gcloud service-management deploy openapi.json". The command returns successfully: Service

How to reference array item examples in OpenAPI 3?

阅读更多关于 How to reference array item examples in OpenAPI 3?

问题 Using this schema definition: schemas: AllContacts: type: array items: $ref: '#/definitions/ContactModel1' example: - id: 1 firstName: Sherlock lastName: Holmes - id: 2 firstName: John lastName: Watson I get this expected result: [ { "id": 1, "firstName": "Sherlock", "lastName": "Holmes" }, { "id": 2, "firstName": "John", "lastName": "Watson" } ] Now I'd like to reuse the Holmes example for both the single user ( ContactModel1 ) and as part of an array of users ( AllContacts ). But if I use

Swagger Codegen (with maven plugin) for OpenAPI 3.0

阅读更多关于 Swagger Codegen (with maven plugin) for OpenAPI 3.0

问题 I want to use Swagger Codegen for OpenAPI 3.0 YAML file. And I see Swagger Codegen 3.0.0-rc0 is available. But when I try to use that I run into issues. Following are the details: My pom.xml file with swagger-codegen plugin: <plugin> <groupId>io.swagger</groupId> <artifactId>swagger-codegen-maven-plugin</artifactId> <version>3.0.0-rc0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${basedir}/src/main/resources/mySpec.yaml</inputSpec>

Write swagger doc that consumes multiple content types e.g. application/json AND application/x-www-form-urlencoded (w/o duplication)

阅读更多关于 Write swagger doc that consumes multiple content types e.g. application/json AND application/x-www-form-urlencoded (w/o duplication)

I'm looking for an elegant way to define an api that can consume JSON data as well as form data. The following snippet works, but it's not elegant and requires all kind of ugly code in the backend. Is there a better way to define this? What works right now: paths: /pets: post: consumes: - application/x-www-form-urlencoded - application/json parameters: - name: nameFormData in: formData description: Updated name of the pet required: false type: string - name: nameJSON in: body description: Updated name of the pet required: false type: string Basic idea of how I'd like it to work: paths: /pets: