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: apiteam@swagger.io
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

3)Spring程序main入口

package com.learning.java;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}

4) Controller 层

package com.learning.java.controller;

import com.learning.java.api.StudentServerApi;
import com.learning.java.model.Student;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController; import java.net.URI; @RestController
public class StudentServerController implements StudentServerApi {
@Override
public ResponseEntity<Void> addStudent(Student body) {
return ResponseEntity.created(URI.create("/v1/students" + body.getName())).build();
}
}

5. 编译自动生成接口文件及model文件

6. 集成spring文档能力

参考文档 https://www.baeldung.com/spring-rest-openapi-documentation

        <dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.4</version>
</dependency>

7. 启动服务

8.  访问服务接口文档及调试

本地启动地址 http://localhost:8080/swagger-ui.html

该页面与yaml接口定义时展示的界面基本一致,只不过这个页面是基于RestController层的接口生成的swaggerui界面,而前面是基于OpenAPI 3规范定义的接口生成的swaggerui页面

可在此页面发起调试,找到对应接口Try it out,输入对应参数,发起调试,会给我们生成curl命令,同时可以收到Server response

 

使用Swagger和OpenAPI 3规范定义API接口并集成到SpringBoot的更多相关文章

  1. day71:drf:API接口&Restful API规范&Django Rest Framework&drf中的序列化和反序列化功能

    目录 1.web应用模式 2.API接口 3.Restful API规范 4.序列化 5.Django Rest Framework 1.drf的简单介绍 2.drf的特点 3.如何安装drf 4.d ...

  2. 微服务手册:API接口9个生命节点,构建全生命周期管理

    互联网应用架构:专注编程教学,架构,JAVA,Python,微服务,机器学习等领域,欢迎关注,一起学习. 对于API,在日常的工作中是接触最多的东西,特别是我们软件这一行,基本就是家常便饭了,在百度百 ...

  3. 循序渐进VUE+Element 前端应用开发(13)--- 前端API接口的封装处理

    在前面随笔<循序渐进VUE+Element 前端应用开发(12)--- 整合ABP框架的前端登录处理>介绍了一个系统最初接触到的前端登录处理的实现,但往往对整个系统来说,一般会有很多业务对 ...

  4. 使用 Swagger 文档化和定义 RESTful API

    大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API——REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...

  5. (29)ASP.NET Core3.1 Swagger(OpenAPI)

    1.什么是Swagger/OpenAPI? Swagger是一个与语言无关的规范,用于描述REST API.因为Swagger项目已捐赠给OpenAPI计划,所以也叫OpenAPI.它允许计算机和人员 ...

  6. Swagger解决你手写API接口文档的痛

    首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛     苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...

  7. ASP.NET Core 3.1使用Swagger API接口文档

    Swagger是最流行的API开发工具,它遵循了OpenAPI规范,可以根据API接口自动生成在线文档,这样就可以解决文档更新不及时的问题.它可以贯穿于整个API生态,比如API的设计.编写API文档 ...

  8. Swagger API接口管理

    介绍         Swagger API框架,用于管理项目中API接口,属当前最流行的API接口管理工具. Swagger功能强大,UI界面漂亮,支持在线测试等!         Swagger包 ...

  9. API接口通讯参数规范(2)

    针对[API接口通讯参数规范]这篇文章留下的几个问题进行探讨. 问题1 试想一下,如果一个http请求返回一个500给我们,那我们是不是都不用看详情都知道该次请求发生了什么?这正是一个标准的结果码意义 ...

  10. Swagger介绍-一套流行的API框架

    简介 号称:世界最流行的API框架 官网:http://swagger.io/ 解决什么问题:在前后台分离的开发模式中,减小接口定义沟通成本,方便开发过程中测试,自动生成接口文档. 实例代码位置:ht ...

随机推荐

  1. uniapp 返回上一页事件监听

    需求 点击订单页---订单详情页----点击修改地址---来到地址列表,修改地址--- 成功以后返回订单详情页,并且更新界面数据 首先在订单详情页   设置事件  监听另一界面触发事件后  就会执行并 ...

  2. Python3中Super函数的使用

    Super函数用法 主要用于调用父类函数 代码演示 class A: def __init__(self): self.n = 2 print('此时执行A的自定义函数,self的n值为',self. ...

  3. windows注册表的读

    1.打开 2.读取 //打开注册表 CString CDownDlg::GetPortCom(int nmber)//读取操作表,其类型为REG_SZ { CString ans; CString r ...

  4. 面向对象程序设计第三次blog

    一.前言 第六次题目集总结-- 题量:较少 难度:较高 知识点: 判断输入内容 提取输入的有效信息并进行计算 总结:题目比较难,题量较少. 第七次题目集总结-- 题量:较少 难度:一般 知识点: 输入 ...

  5. 新的学习历程-python3 基本运算

    1 print(5 / 2) # 2.5 2 print(5 // 3) #1 取整除 3 print(5 % 3) #2 取余数(取模) 4 print(5 ** 2) #25 5的2次方 5 pr ...

  6. Windows 脚本放到 Linux 服务器不生效的问题 /bin/bash^M: bad interpreter: No such file or directory

    在windows编辑shell脚本后,由于文件格式原因,在linux下运行报错 有三个方法 1.在windows下,使用notepad++,将文件格式改为unix就可以了 2.在linux下,使用vi ...

  7. JavaSE——遍历字符串与统计字符个数

    package com.zhao.stringtest; import java.util.Scanner; public class test2 { //键盘录入一个字符串,统计该字符串中大写字母, ...

  8. 错误 : 资产文件&ldquo;\obj\project.assets.json&rdquo;没有&ldquo;.NETCoreApp,Version=v2.0&rdquo;的目标。确保已运行还原,且&ldquo;netcoreapp2.0&rdquo;已包含在项目的 TargetFrameworks 中。

    原因是项目升级了目标框架netcoreapp2.1但是发布配置文件上的目标框架配置项没有更改导致发布错误 将此处修改成需要的版本即可.例如:<TargetFramework>netcore ...

  9. jar包下不下来

    1.maven中的settings.xml文件中的镜像资源配置 <mirror> <id>alimaven</id> <name>aliyun mave ...

  10. vue-表格拖拽

    1. el-table结合sortable 参考:https://blog.csdn.net/weixin_42460570/article/details/125765599?ops_request ...