1. OpenAPI 3 规范介绍及属性定义
参考官方定义：https://swagger.io/specification/
2. 使用OpenAPI 3规范定义API接口
官方样例参考：https://editor.swagger.io/
可以在此页面进行编辑，编辑后的效果所见即所得
3. SwaggerUI展示及调试
左侧的接口定义好后，在右侧会出现相应的接口定义及响应参考相关信息，所见即所得，并且可以调试。
4. 接口定义集成到SpringBoot项目自动生成接口
1）pom.xml文件引入swagger-codegen-maven-plugin用于基于swagger定义的接口yaml文件生成对应的接口Java代码。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.5.6</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<properties>
<java.version>8</java.version>
</properties>
<groupId>com.learning.java</groupId>
<artifactId>snippet</artifactId>
<version>1.0</version>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.4</version>
</dependency>
<dependency>
<groupId>javax.validation</groupId>
<artifactId>validation-api</artifactId>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.1.11</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.20</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>io.swagger.codegen.v3</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>3.0.29</version>
<!--https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen-maven-plugin/README.md#general-configuration-parameters-->
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/yaml/student.yaml</inputSpec>
<language>spring</language>
<apiPackage>com.learning.java.api</apiPackage>
<modelPackage>com.learning.java.model</modelPackage>
<configOptions>
<delegatePattern>true</delegatePattern>
<interfaceOnly>true</interfaceOnly>
<java8>true</java8>
<useTags>true</useTags>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2）项目的src/main/resources/yaml/student.yaml文件为接口定义文件
openapi: 3.0.3
info:
title: Swagger Student
version: 1.0.0
description: "学生服务，可对学生信息进行增删改查操作"
termsOfService: http://swagger.io/terms/
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Find out more about Swagger
url: http://swagger.io
servers:
- url: https://student.swagger.io/v2
- url: http://student.swagger.io/v2
tags:
- name: StudentServer
description: "学生服务"
externalDocs:
description: Find out more
url: http://swagger.io
paths:
/v1/students:
post:
tags:
- StudentServer
summary: "新增一个学生"
operationId: AddStudent
requestBody:
description: "学生信息"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Student'
example:
id: 0
name: "张三"
age: 18
sex: "boy"
responses:
201:
description: Created
400:
description: Bad Request
401:
description: Unauthorized
403:
description: Forbidden
x-request-examples-description-1: "新增学生请求示例"
x-request-examples-url-1: "POST https://{endpoint}/v1/students"
x-request-examples-1:
id: 0
name: "张三"
age: 18
sex: "boy"
put:
tags:
- StudentServer
summary: "更新学生信息"
operationId: UpdateStudent
requestBody:
description: "学生信息"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Student'
example:
id: 0
name: "张三"
age: 18
sex: "boy"
responses:
200:
description: OK
400:
description: Bad Request
401:
description: Unauthorized
403:
description: Forbidden
x-request-examples-description-1: "更新学生请求示例"
x-request-examples-url-1: "PUT https://{endpoint}/v1/students"
x-request-examples-1:
id: 0
name: "张三"
age: 18
sex: "boy"
/v1/students/{id}:
get:
tags:
- StudentServer
summary: "通过学号查询学生信息"
operationId: ShowStudentById
parameters:
- name: id
in: path
description: "学号"
required: true
schema:
type: integer
format: int32
minimum: 0
maximum: 100
example: 0
responses:
200:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Student'
example:
id: 0
name: "张三"
age: 18
sex: "boy"
400:
description: Bad Request
401:
description: Unauthorized
403:
description: Forbidden
404:
description: Not Found
x-request-examples-description-1: "查询学生信息请求示例"
x-request-examples-url-1: "GET https://{endpoint}/v1/students/0"
delete:
tags:
- StudentServer
summary: "删除学生信息"
operationId: DeleteStudentById
parameters:
- name: id
in: path
description: "学号"
required: true
schema:
type: integer
format: int32
minimum: 0
maximum: 100
example: 0
responses:
204:
description: No Content
400:
description: Bad Request
401:
description: Unauthorized
403:
description: Forbidden
404:
description: Not Found
x-request-examples-description-1: "删除学生请求示例"
x-request-examples-url-1: "DELETE https://{endpoint}/v1/students/0"
components:
schemas:
Student:
description: "学生信息"
required:
- id
- name
- age
- sex
properties:
id:
description: "学号"
type: integer
format: int32
minimum: 0
maximum: 100
example: 0
name:
description: "姓名"
type: string
minLength: 0
maxLength: 10
example: "张三"
age:
description: "年龄"
type: integer
format: int32
minimum: 6
maximum: 30
example: 18
sex:
description: "性别"
type: string
enum:
- boy
- girl
minLength: 3
maxLength: 4
example: boy
标签：swagger,description,OpenAPI,API,examples,io,Swagger,id,name From： https://www.cnblogs.com/xiang-siyu/p/17032437.html