Shulou(Shulou.com)06/01 Report--

What is the overview of OpenAPI? for this question, this article introduces the corresponding analysis and answer in detail, hoping to help more partners who want to solve this problem to find a more simple and feasible way.

The so-called OpenAPI refers to the OpenAPI specification (OpenAPI Specification), referred to as OAS, which is used to standardize the RESTful-style API description method.

There are many ways to describe the API of a web service, such as using a world file description, but such an API description is not general enough. The OpenAPI specification defines a general interface description method. Defining the interface according to this specification is not only suitable for people to read, but also convenient for program processing.

History of development

The predecessor of the OpenAPI specification is the Swagger specification, which developed from a project called Swagger API.

In 2011, Tony Tam, an American engineer, created the Swagger API project, which consists of an early specification and a series of tools, also known as the Swagger specification.

The project did not develop smoothly in the first few years, only some small companies and individual developers approved the project, and there were some competitors in the industry, such as RAML, which is also used to describe API. Although the Swagger specification is still much hotter than its competitors, it only benefits from the first-mover advantage of the Swagger API project. Competitors emerged in the same period have a strong background and financial support, the long-term development of the Swagger API project is bound to fall at a disadvantage, and then can only become a forgotten entry in the history of Internet development.

If the Swagger API project is to continue to develop, it needs not only financial support, but also the approval of Internet big companies such as Google. Only in this way can Swagger specification become a common specification in the industry.

In 2015, Tony Tam, the founder of the Swagger API project, moved to SmartBear Software, and with the support of the company, the Swagger API project made a change that laid the foundation for the future.

Also in 2015, SmartBear Software donated the Swagger specification to the Linux Foundation, and the Linux Foundation set up a new project, OpenAPI Initiative, to host the specification. The founding members of the new project include Google, IBM and Microsoft. In this way, the Swagger specification has been supported by large Internet companies and can continue to develop.

Then, the Swagger specification was spun off from the original Swagger API project, renamed to the OpenAPI specification and hosted to the OpenAPI Initiative project, and the tools related to the specification were still retained in the Swagger API project.

Since then, under the operation of the Linux Foundation, the OpenAPI specification has gradually become the de facto standard in the industry, while SmartBear Software, the former sponsor of the Swagger API project, continues to operate specification-related tools, which are downloaded 100000 times a day, according to 2017 statistics.

Specification version

When SmartBear Software donated the Swagger specification to the Linux Foundation, the version of the Swagger specification was 2.0. it is customary in the industry to name the API file described with the specification swagger.json. At this time, the version 2.0 of the Swagger specification is completely consistent with that of the OpenAPI specification, which is only a rename of the specification.

Under the operation of the Linux Foundation, the OpenAPI specification continued to evolve and released version 3.0 in 2017, which supports not only the description of API in JSON format but also the format of YAML. According to the specification, files describing API using this version of the specification are recommended to be named openapi.json or openapi.yaml.

Schema

Schema is often translated simply as a schema, but it often represents the organization and structure of things. For example, the schema of a database represents the organization and structure of a database. Similarly, the OpenAPI specification also defines a set of schema objects to represent a complete OpenAPI specification file.

Each version of the OpenAPI specification has different schema objects, and since Kubernetes (v1.18.0) is still using version 2.0 of the OpenAPI specification, this article only introduces a few schema objects used by Kubernetes. Please refer to the specification for more details.

Access the / openapi/v2 interface of kube-apiserver to get the complete interface description file, such as executing the following command in the local cluster:

[root@ecs-d8b6 ~] # curl localhost:8080/openapi/v2

This command outputs the complete interface description file. The file consists of a series of fields, each of which is called a schema object, and is divided into required and optional fields.

Required field: swagger

The swagger field is used to describe the version of the specification, and the field type is string. For example, the swagger field of Kubernetes is as follows:

{"swagger": "2.0",...}

This field indicates the specification version of the current API document and is mainly used by the relevant tools to identify and process the document.

Required field: info

The info field is used to describe the basic information of API, and the field type is Info Object. The Info Object type contains the following two required fields:

Title: the type is string, indicating the name of the application.

Version: type string, indicating the version of the application.

For example, the info field of Kubernetes is as follows:

{"info": {"title": "Kubernetes", "version": "v1.19.0"},...}

The info field indicates that the document records the interface for version v1.19.0 of Kubernetes.

Required field: paths

The paths field is used to describe the endpoints of the API and the supported operations, and the field type is Paths Object. The Paths Object type is made up of the Path Item Object type, and the endpoint / api description of the Kubernetes is as follows:

{"paths": {"/ api/": {"get": {"description": "get available API versions", "consumes": ["application/json" "application/yaml", "application/vnd.kubernetes.protobuf"], "produces": ["application/json" "application/yaml", "application/vnd.kubernetes.protobuf"] "schemes": ["https"], "tags": ["core"] "operationId": "getCoreAPIVersions", "responses": {"200": {"description": "OK" "schema": {"$ref": "# / definitions/io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions"}} {"description": "Unauthorized"} ...}}

From the above information, we can see that the endpoint (interface) / api/ supports get operation, using consumes to indicate the media type supported by the interface, produces to indicate the media type supported by the interface, and responses to indicate the possible return value.

Where $ref refers to another custom object.

Optional field: definitions

The definitions field is used to define a set of objects of type Definitions Object that are referenced (consumed or generated) by each interface.

{"definitions": {"io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions": {"description": "APIVersions lists the versions that are available,...", "type": "object", "required": ["versions" "serverAddressByClientCIDRs"], "properties": {. "kind": {"description": "Kind is a string value representing the REST resource...", "type": "string"} "serverAddressByClientCIDRs": {"description": "a map of client CIDR to server address that is serving this group , "type": "array" "items": {"$ref": "# / definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ServerAddressByClientCIDR"}} "versions": {"description": "versions are the api versions that are available.", "type": "array" "items": {"type": "string"}} ...},...}}

In a nutshell, fields defined using the definitions field can be referenced by multiple operations for reuse. When you need to reference other objects, you only need to use $ref to specify the reused objects, as shown below:

"$ref": "# / definitions/ object name"

The object io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions is referenced in the above infos field to indicate the returned content after a successful call to the API. The object indicates that versions and serverAddressByClientCIDRs information will be returned. The output after the successful call is as follows:

[root@ecs-d8b6 ~] # curl localhost:8080/api/ {"kind": "APIVersions", "versions": ["v1"], "serverAddressByClientCIDRs": [{"clientCIDR": "0.0.0.0 OpenAPI 0", "serverAddress": "localhost:6443"}]} this is the answer to the question about the overview of OpenAPI. I hope the above content can be helpful to you. If you still have a lot of questions to solve, you can follow the industry information channel to learn more about it.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.