概述

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

简单一句话，OpenAPI规范定义了一个标准、跟编程语言无关的rest API接口描述，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。

当定义完OpenAPI，可以使用工具生成代码。简化开发。

数据类型

Data Types

OpenAPI 的组件

OpenAPI组件

OpenAPI文档结构

Components内容

Components组件

Parameter参数

reponse部分

Path部分

path部分

生成api

当写完这个api.yml，然后放在editor.swagger里面，可得到下面的结果：

editor.swagger

使用命令生成代码

java -jar swagger-codegen-cli.jar generate -DdateLibrary=joda --api-package com.swagger.v1 --model-package com.swagger.v1.model --group-id demo1.swagger --artifact-id project-foundation-domain --artifact-version 0.1.0-SNAPSHOT --additional-properties useTags=true -l spring -i C:/Users/BinYang/Desktop/project/backend/learning-swagger.yml -o C:/Users/BinYang/Desktop/project/backend/swagger