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