百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 编程网 > 正文

Springboot OpenAPI文档生成器Swagger

yuyutoo 2024-10-12 01:50 2 浏览 0 评论



一、Swagger介绍

Swagger是一个开源文档生成器,可以方便的用来生成OpenAPI规格的接口文档,支持Go、Python、Haskell、Java等多种语言,同时支持在线调试接口。

官网:
https://swagger.io

Swagger 工具集包含:
? Swagger Editor – 在线编写 OpenAPI 规范的编辑器
? Swagger UI – 使用 OpenAPI 规范生成的交互式文档
? Swagger Codegen – 使用 OpenAPI 规范分别生成客户端/服务器代码(Server-stub)的工具

同类型的工具还有:

  • docway

附:OpenAPI 中文文档:https://fishead.gitbooks.io/openapi-specification-zhcn-translation/content/versions/3.0.0.zhCN.html#oasDocument

二、java下的使用

1. 加入依赖

在Springboot环境下的使用十分简单,只需要加入依赖:

<!-- swagger-ui -->
        <dependency>![在这里插入图片描述](https://img-blog.csdnimg.cn/20200927135341240.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1bmRo,size_16,color_FFFFFF,t_70#pic_center)

            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>

2. 书写SwaggerConfig文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket ProductApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.genericModelSubstitutes(DeferredResult.class)
				.useDefaultResponseMessages(false)
				.forCodeGeneration(false)
				.pathMapping("/")
				.select()
				.build()
				.apiInfo(productApiInfo());
	}

	private ApiInfo productApiInfo() {
		ApiInfo apiInfo = new ApiInfo("XXX系统数据接口文档",
				"文档描述。。。",
				"1.0.0",
				"API TERMS URL",
				"联系人邮箱",
				"license",
				"license url");
		return apiInfo;
	}
}

启动Springboot项目后,就可以通过 http://localhost:8080/swagger-ui.html:
来访问接口:

3. 接口注解

2.3.1 controller上的注解

@Api(value="用户controller",tags={"用户操作接口"})
@Controller
@RequestMapping("web/user")
public class UserController {

}

2.3.2 方法上的注解

    @GetMapping("/userInfo")
    @ResponseBody
    @ApiOperation(value = "查询个人信息", tags = {"返回用户信息"}, notes = "提交json格式")
    public Result userInfo(@ApiParam(name="phone",value="用户手机号",required=true)String phone) {
    	Result result = new Result();
        return result;
    }

2.3.3 实体类上的注解

@ApiModel(description="登录请求参数")
public class UserLoginDto {

    @ApiModelProperty(value="用户电话", required=true)
    private String phone;

    @ApiModelProperty(value="密码", required=true)
    private String password;

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

}

2.3.4 常用注解说明

  • @Api() 用于类,表示swagger的注解资源
  • @ApiOperation() 用于方法,表示一个http请求
  • @ApiParam(),用于方法的参数,说明字段使用
  • @ApiModel(),于用实体类
  • @ApiIgnore 用于类、方法、方法参数,表示这个方法或类被忽略
  • @ApiImplicitParam() 用于方法,表示单独的请求参数
  • @ApiImplicitParams()用于方法,包含多个 @ApiImplicitParam
  • @ApiResponses() 用于方法,包含多个 @ApiResponse

三、更换前端UI

默认的swagger-ui不怎么符合国人的审美观。好在有一些好心的开发者提供了更漂亮的API界面,下面简单介绍几款:

1. knife4j

为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。使用该工具还可以方便的生成md格式接口源文件。
其功能比较多,只更换swagger-ui的话引用:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

或者使用老版本:

        <!-- 引入swagger-bootstrap-ui包 /doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

界面效果:


2. Swagger-UI-layer

地址: https://gitee.com/caspar-chen/Swagger-UI-layer
引用:

<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>${last-version}</version>
</dependency>

效果:


doc访问地址: http://****/docs.html

3. tennetcn

引用:

<dependency>
  <groupId>com.tennetcn.free</groupId>
  <artifactId>think-swagger-ui-starter</artifactId>
  <version>0.0.4</version>
</dependency>

效果:


4. swagger-mg-ui

引用:

<!-- https://mvnrepository.com/artifact/com.zyplayer/swagger-mg-ui -->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

效果:

5. swagger-document-ui

引用:
移除官方 UI 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>

添加 swagger-document-ui 依赖

<dependency>
    <groupId>cn.javaer.springfox</groupId>
    <artifactId>swagger-document-ui</artifactId>
    <version>1.0.2</version>
</dependency>

开源地址:https://gitee.com/cn-src/swagger-document-ui
效果:

相关推荐

野路子科技!2步教你把手机改造成一个FTP服务器,支持PC互传

哈喽,大家好,我是野路子科技,今天来给大家带来一个教程,希望大家喜欢。正如标题所言,就是教大家如何把售价改造成FTP服务器,而这个时候估计有朋友会问了,把手机改造成FTP服务器有什么用呢?现在有Q...

不得不看:别样于Server-U的群晖文件存储服务器的搭建与使用

我先前的作品中,有着关于Server-U的ftp文件存储服务器的搭建与访问的头条文章和西瓜视频,而且我们通过各种方式也给各位粉丝介绍了如何突破局域网实现真正意义上的公网访问机制技术。关于Server-...

Qt三种方式实现FTP上传功能_qt引入qftp库

FTP协议FTP的中文名称是“文件传输协议”,是FileTransferProtocol三个英文单词的缩写。FTP协议是TCP/IP协议组中的协议之一,其传输效率非常高,在网络上传输大的文件时,经...

Filezilla文件服务器搭建及客户端的使用

FileZilla是一个免费开源的FTP软件,分为客户端版本和服务器版本,具备所有的FTP软件功能。可控性、有条理的界面和管理多站点的简化方式使得Filezilla客户端版成为一个方便高效的FTP客户...

美能达柯美/震旦复印机FTP扫描怎么设置?

好多网友不知道怎么安装美能达/震旦复印机扫描,用得最多是SMB和FTP扫描,相对于SMB来说,FTP扫描安装步骤更为便捷,不容易出问题,不需要设置文件夹共享,所以小编推荐FTP来扫描以美能达机器为例详...

CCD(简易FTP服务器软件)_简单ftp服务器软件

CCD简易FTP服务器软件是一款很方便的FPT搭建工具,可以将我们的电脑快速变成一个FPT服务器。使用方法非常简单,只要运行软件就会自动生效,下载银行有该资源。该工具是不提供操作界面的,其他用户可以输...

Ubuntu系统搭建FTP服务器教程_ubuntu架设服务器

在Ubuntu系统上搭建FTP服务器是文件传输的一个非常实用方法,适合需要进行大量文件交换的场景。以下是一步步指导,帮助您在Ubuntu上成功搭建FTP服务器。1.安装vsftpd软件...

理光FTP扫描设置教程_理光ftp扫描设置方法

此教程主要用来解决WIN10系统下不能使用SMB文件夹扫描的问题,由于旧的SMB协议存在安全漏洞,所以微软在新的系统,WIN8/WIN10/SERVER201220162018里使用了新的SMB传...

纯小白如何利用wireshark学习网络技术

写在前面工欲善其事必先利其器!熟悉掌握一种神器对以后的工作必然是有帮助的,下面我将从简单的描述Wireshark的使用和自己思考去写,若有错误或不足还请批评指正。...

京东买13盘位32GB内存NAS:NAS系统安装设置教程

本内容来源于@什么值得买APP,观点仅代表作者本人|作者:yasden你没有看错,我在京东自营商城购买硬件,组装了一台13盘位,32GB内存的NAS,硬盘有13个盘位!CPU是AMD的5500!本文...

FileZilla搭建FTP服务器图解教程_filezilla server搭建ftp服务器

...

python教程之FTP相关操作_python ftps

ftplib类库常用相关操作importftplibftp=ftplib.FTP()ftp.set_debuglevel(2)#打开调试级别2,显示详细信息ftp.connect(“I...

xftp怎么用,xftp怎么用,具体使用方法

Xftp是一款界面化的ftp传输工具,用起来方便简单,这里为大家分享下Xftp怎么使用?希望能帮到有需要的朋友。IIS7服务器管理工具可以批量管理、定时上传下载、同步操作、数据备份、到期提醒、自动更新...

树莓派文件上传和下载,详细步骤设置FTP服务器

在本指南中,详细记录了如何在树莓Pi上设置FTP。设置FTP可以在网络上轻松地将文件传输到Pi上。FTP是文件传输协议的缩写,只是一种通过网络在两个设备之间传输文件的方法。还有一种额外的方法,你可以用...

win10电脑操作系统,怎么设置FTP?windows10系统设置FTP操作方法

打印,打印,扫描的日常操作是每一个办公工作人员的必需专业技能,要应用FTP作用扫描文件到电脑上,最先要必须一台可以接受文件的FTP服务器。许多软件都需要收费标准进行,但人们还可以应用Windows的系...

取消回复欢迎 发表评论: