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. vscode注释插件

    VSCODE注释插件:koro1FileHeader 按koroFileHeader 插件,配置默认注释 1.在扩展中搜索koroFileHeader,安装 2.安装完成后,在设置中搜索,koro1F ...

  2. 这里记录一下我个人对AXI4主从模块的理解(这些理解主要来自阅读 Xilinx AXI_FULL_M_module 源码)

    先只考虑读请求: 以取指模块和内存模块为例,取指模块是发出请求的模块,因此为 Master,属于AXI4MasterModule:内存模块是响应请求的模块,因此为 Slave,属于AXI4SlaveM ...

  3. 360 quake 网络空间测绘引擎真的很不错

    最近通过使用360 quake搜索引擎,发现真的能够比较准确的找到数据,对比fofa,shodan这种免费用户使用体验真的很好,搜到的数据很是全面,但是搜索的资产是国内的ip时会做脱敏处理.有时间大家 ...

  4. 设计模式 > 单一职责原则

    SOLID原则并非单纯的1个原则,而是由5个设计原则组成的,它们分别是单一职责原则,开闭原则,里氏替换原则,接口隔离原则和依赖反转原则. 单一职责原则(SRP) 定义:一个类或者模块只负责完成一个职责 ...

  5. springboot-maven打包项目

    在project 标签内,新增一下内容 <build> <plugins> <!--打包项目--> <plugin> <groupId>or ...

  6. JRebel for IDEA插件 激活

    JRebel for IDEA 插件的License Server 程序,在IDEA中下载JREBEL的插件后,通过配置此服务进行插件激活. 使用方法:通过java -jar JrebelBrains ...

  7. Unity 打包到XCode自动化设置参数

    [PostProcessBuild] public static void OnPostprocessBuild(BuildTarget buildTarget, string buildPath) ...

  8. 查看nohup.out 日志文件

    1.查看实时日志: tail -f nohup.out 2.查看实时日志并检索关键字: tail -f nohup.out | grep "关键字" 3.查看文件最后100行日志: ...

  9. pytorch学习笔记(9)--神经网络模型的保存与读取

    一.网络模型的保存和加载 1.网络模型保存方法1 import torch import torchvision vgg16 = torchvision.models.vgg16(weights=Fa ...

  10. java HashMap 原理

    jdk1.7 和 1.8 大致相同但还是有区别,主要是数据结构的区别,1.7 为数组+链表:1.8 为数组+链表+红黑树 关键知识点 加载因子:装填因子,目的是何时对 map 进行扩容,默认是 0.7 ...