[springboot 开发单体web shop] 4. Swagger生成Javadoc
Swagger生成JavaDoc
在日常的工作中,特别是现在前后端分离模式之下,接口的提供造成了我们前后端开发人员的沟通
成本大量提升,因为沟通不到位,不及时而造成的[撕币]事件都成了日常工作。特别是很多的开发人员
不擅长沟通,造成的结果就会让自己特别的痛苦,也让合作人员恨
的牙根痒痒。
为了结束战火蔓延,同时为了提升开发人员的满意度,Swagger
应运而生。
什么是Swagger
Swagger for Everyone
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.
Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.
简言之就是指使用工具集简化用户、团队和企业的API开发。
集成Swagger
系统中我选择使用的是swagger-spring-boot-starter
。
该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。
看得出来,我在教大家使用的都是在偷懒哦,这可不是什么好现象。。。
添加依赖
<!--整合Swagger2-->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
点击版本号进入swagger-spring-boot-starter/1.9.0.RELEASE/swagger-spring-boot-starter-1.9.0.RELEASE.pom
,可以看到它依赖的版本信息。
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<version.java>1.8</version.java>
<version.swagger>2.9.2</version.swagger>
<version.spring-boot>1.5.10.RELEASE</version.spring-boot>
<version.lombok>1.18.6</version.lombok>
</properties>
启用功能
在我们的启动类ApiApplication
上增加@EnableSwagger2Doc注解
@SpringBootApplication
@MapperScan(basePackages = "com.liferunner.mapper")
@ComponentScan(basePackages = {"com.liferunner", "org.n3r.idworker"})
@EnableSwagger2Doc //启动Swagger
public class ApiApplication {
public static void main(String[] args) {
new SpringApplicationBuilder()
.sources(ApiApplication.class)
.run(args);
}
@Autowired
private CORSConfig corsConfig;
/**
* 注册跨域配置信息
*
* @return {@link CorsFilter}
*/
@Bean
public CorsFilter corsFilter() {
val corsConfiguration = new CorsConfiguration();
corsConfiguration.addAllowedOrigin(this.corsConfig.getAllowOrigin());
corsConfiguration.addAllowedMethod(this.corsConfig.getAllowedMethod());
corsConfiguration.addAllowedHeader(this.corsConfig.getAllowedHeader());
corsConfiguration.setAllowCredentials(this.corsConfig.getAllowCredentials());
val urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
return new CorsFilter(urlBasedCorsConfigurationSource);
}
}
配置基础信息
可以通过properties
文件和yml/yaml
文件配置。
# 配置swagger2
swagger:
enabled: true #是否启用swagger,默认:true
title: 实战电商api平台
description: provide 电商 API
version: 1.0.0.RC
license: Apache License, Version 2.0
license-url: https://www.apache.org/licenses/LICENSE-2.0.html
terms-of-service-url: http://www.life-runner.com
contact:
email: magicianisaac@gmail.com
name: Isaac-Zhang
url: http://www.life-runner.com
base-package: com.liferunner
base-path: /**
阶段效果一
运行我们的api项目,在浏览器输入:http://localhost:8088/swagger-ui.html
,可以看到如下:
可以看到,我们在yml
文件中配置的信息,展示在了页面的顶部,点击用户管理
:
从上图可以看出,我们的/users/create
接口展出出来,并且要传入的参数,请求类型等等信息都已经展示在上图中。
但是,要传递的参数是什么意思,都是我们的字段信息,我们要如何让它更友好的展示给调用方呢?让我们继续
完善我们的文档信息:
完善说明信息
在我们创建用户的时候,需要传递一个com.liferunner.dto.UserRequestDTO
对象,这个对象的属性如下:
@RestController
@RequestMapping(value = "/users")
@Slf4j
@Api(tags = "用户管理")
public class UserController {
@Autowired
private IUserService userService;
@ApiOperation(value = "用户详情", notes = "查询用户")
@ApiIgnore
@GetMapping("/get/{id}")
//@GetMapping("/{id}") 如果这里设置位这样,每次请求swagger都会进到这里,是一个bug
public String getUser(@PathVariable Integer id) {
return "hello, life.";
}
@ApiOperation(value = "创建用户", notes = "用户注册接口")
@PostMapping("/create")
public JsonResponse createUser(@RequestBody UserRequestDTO userRequestDTO) {
//...
}
}
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel(value = "创建用户DTO", description = "用户注册需要的参数对象")
public class UserRequestDTO {
@ApiModelProperty(value = "用户名", notes = "username", example = "isaaczhang", required = true)
private String username;
@ApiModelProperty(value = "注册密码", notes = "password", example = "12345678", required = true)
private String password;
@ApiModelProperty(value = "确认密码", notes = "confimPassword", example = "12345678", required = true)
private String confirmPassword;
}
可以看到,我们有很多通过@Apixxx
开头的注解说明,这个就是Swagger提供给我们用以说明字段和文档说明的注解。
@Api
表示对外提供API@ApiIgnore
表示不对外展示,可用于类和方法@ApiOperation
就是指的某一个API下面的CURD动作@ApiResponses
描述操作可能出现的异常情况@ApiParam
描述传递的单参数信息@ApiModel
用来描述java object的属性说明@ApiModelProperty
描述object 字段说明
所有的使用,都可以进入到相关的注解的具体class去查看所有的属性信息,都比较简单,这里就不做具体描述了。想要查看更多的属性说明,
大家可以进入:Swagger属性说明传送门。
配置完之后,重启应用,刷新UI页面:
上图中红框圈定的都是我们重新配置的说明信息,足够简单明了吧~
集成更好用的UI界面
针对于API说明来说,我们上述的信息已经足够优秀了,可是做技术,我们应该追求的是更加极致的地步,上述的UI界面在我们提供大批量
用户接口的时候,友好型就有那么一丢丢的欠缺了,现在给大家再介绍一款更好用的开源Swagger UI
,有请swagger-bootstrap-ui。
我们从上图可以看到,这个UI的Star数目已经超过1.1K了,这就证明它已经很优秀了,我们接下来解开它的庐山真面目吧。
集成依赖
只需要在我们的expensive-shop\pom.xml
中加入以下依赖代码:
<!--一种新的swagger ui-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
预览效果
添加完依赖后,只需要重启我们的应用,然后访问http://localhost:8088/doc.html
,效果如下:
点击创建用户:
上述的效果是不是更符合我们的审美了~
到此为止,我们使用Swagger
来动态生成API的效果已经全部演示完了,但是如果某一天我们要和一个不能连接查看我们网站的客户进行集成的时候,我们怎么办呢?
还是要手写一份文档给他们吗? 那我们不就一样很痛苦吗!!!
作为程序员,我们是绝对不能允许这种情况发生的!
那就让我们继续看下去。
生成离线文档
为了不让我们做痛苦的工作,我们既然已经在代码中添加了那么多的说明信息,是否有一种方式可以帮助我们来生成一份离线的文档呢?答案是肯定的。
开源项目swagger2markup
A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.
Swagger2Markup它主要是用来将Swagger自动生成的文档转换成几种流行的格式以便离线使用
格式:AsciiDoc、HTML、Markdown、Confluence
使用MAVEN插件生成AsciiDoc文档
在mscx-shop-api\pom.xml
中加入以下依赖代码:
<build>
<plugins>
<!--生成 AsciiDoc 文档(swagger2markup)-->
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.3</version>
<configuration>
<!--这里是要启动我们的项目,然后抓取api-docs的返回结果-->
<swaggerInput>http://localhost:8088/v2/api-docs</swaggerInput>
<outputDir>src/docs/asciidoc/generated-doc</outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
</config>
</configuration>
</plugin>
</plugins>
</build>
<swaggerInput>http://localhost:8088/v2/api-docs</swaggerInput>
是为了获取我们的api JSON
数据,如下图:
<outputDir>src/docs/asciidoc/generated-doc</outputDir>
设置我们要生成的目录地址
执行命令:
expensive-shop\mscx-shop-api>mvn swagger2markup:convertSwagger2markup
要是大家觉得命令太长了,也可以点击IDEA => Maven => mscx-shop-api => Plugins => swagger2markup => swagger2markup:convertSwagger2markup
就可以执行啦,如下图:
生成结果如下:
adoc文件生成好了,那么我们使用它来生成html吧
使用MAVEN插件生成HTML
在mscx-shop-api\pom.xml
中加入以下依赖代码:
<!--生成 HTML 文档-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated-doc</sourceDirectory>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
</plugin>
<sourceDirectory>src/docs/asciidoc/generated-doc</sourceDirectory>
源文件目录指定为我们上一节生成的adoc<outputDirectory>src/docs/asciidoc/html</outputDirectory>
指定输出目录
执行生成命令:
\expensive-shop\mscx-shop-api>mvn asciidoctor:process-asciidoc
生成结果如下:
打开overview.html
,如下:
至此,我们的文档就已经全部生成了!
下节预告
下一节我们将继续开发我们的用户登录以及首页信息的部分展示,在过程中使用到的任何开发组件,我都会通过专门的一节来进行介绍的,兄弟们末慌!
gogogo!
[springboot 开发单体web shop] 4. Swagger生成Javadoc的更多相关文章
- [springboot 开发单体web shop] 1. 前言介绍和环境搭建
前言介绍和环境搭建 简述 springboot 本身是为了做服务化用的,我们为什么要反其道使用它来开发一份单体web应用呢? 在我们现实的开发工作中,还有大量的业务系统使用的是单体应用,特别是对于中小 ...
- [springboot 开发单体web shop] 2. Mybatis Generator 生成common mapper
Mybatis Generator tool 在我们开启一个新项目的研发后,通常要编写很多的entity/pojo/dto/mapper/dao..., 大多研发兄弟们都会抱怨,为什么我要重复写CRU ...
- [springboot 开发单体web shop] 6. 商品分类和轮播广告展示
商品分类&轮播广告 因最近又被困在了OSGI技术POC,更新进度有点慢,希望大家不要怪罪哦. 上节 我们实现了登录之后前端的展示,如: 接着,我们来实现左侧分类栏目的功能. ## 商品分类|P ...
- [springboot 开发单体web shop] 3. 用户注册实现
目录 用户注册 ## 创建数据库 ## 生成UserMapper ## 编写业务逻辑 ## 编写user service UserServiceImpl#findUserByUserName 说明 U ...
- [springboot 开发单体web shop] 5. 用户登录及首页展示
用户登录及前端展示 用户登录 在之前的文章中我们实现了用户注册和验证功能,接下来我们继续实现它的登录,以及登录成功之后要在页面上显示的信息. 接下来,我们来编写代码. 实现service 在com.l ...
- [springboot 开发单体web shop] 8. 商品详情&评价展示
上文回顾 上节 我们实现了根据搜索关键词查询商品列表和根据商品分类查询,并且使用到了mybatis-pagehelper插件,讲解了如何使用插件来帮助我们快速实现分页数据查询.本文我们将继续开发商品详 ...
- [springboot 开发单体web shop] 7. 多种形式提供商品列表
上文回顾 上节 我们实现了仿jd的轮播广告以及商品分类的功能,并且讲解了不同的注入方式,本节我们将继续实现我们的电商主业务,商品信息的展示. 需求分析 首先,在我们开始本节编码之前,我们先来分析一下都 ...
- 开发单体web shop] 6. 商品分类和轮播广告展示
目录 商品分类&轮播广告 商品分类|ProductCategory 需求分析 开发梳理 编码实现 轮播广告|SlideAD 需求分析 开发梳理 编码实现 福利讲解 源码下载 下节预告 商品分类 ...
- Asp.Net Core Web Api 使用 Swagger 生成 api 说明文档
最近使用 Asp.Net Core Web Api 开发项目服务端.Swagger 是最受欢迎的 REST APIs 文档生成工具之一,进入我的视野.以下为学习应用情况的整理. 一.Swagger 介 ...
随机推荐
- 解决Git报错:error: You have not concluded your merge (MERGE_HEAD exists).
Git fetch和git pull的区别, 解决Git报错:error: You have not concluded your merge (MERGE_HEAD exists). 2017年02 ...
- Kafka0.11之RoundRobinPartitioner/HashPartitioner(Scala):
RoundRobinPartitioner/HashPartitioner: import java.util import java.util.concurrent.atomic.AtomicLon ...
- Linux 下复制整个文件夹的命令
在 Linux 下复制整个文件夹,包括它的子文件夹及其隐藏文件的方法是: cp -r /etc/skel /home/user 或者 mkdir /home/<new_user> cp - ...
- B/S 工业互联网 地铁行业
前言 近几年,互联网与交通运输的融合,改变了交易模式,影响着运输组织和经营方式,改变了运输主体的市场结构.模糊了运营与非营运的界限,也更好的实现了交通资源的集约共享,同时使得更多依靠外力和企业推动交通 ...
- mac系统Intellij Idea的java环境配置:JDK + Tomcat + Maven
一.JAVA JDK查看与配置 1.查看java路径详细信息: /usr/libexec/java_home -V 2.java默认路径 jdk1.6: /System/Library/Java/Ja ...
- 微信开发中使用微信JSSDK和使用URL.createObjectURL上传预览图片的不同处理对比
在做微信公众号或者企业微信开发业务应用的时候,我们常常会涉及到图片预览.上传等的处理,往往业务需求不止一张图片,因此相对来说,需要考虑的全面一些,用户还需要对图片进行预览和相应的处理,在开始的时候我使 ...
- 云计算之走进LINUX(二)
引言 * 第二部分 云计算应用管理 [Shell脚本基础] [使用变量] [条件测试及选择] [列表式循环] [系统安全保护] [配置用户环境] [防火墙策略管理] [ISCSI共享存储] [数据库 ...
- 微信小程序登入流程
微信小程序登入流程 一.首先前端先传code去后端 wx.login({ success(res) { if (res.code) { //发起网络请求 wx.request({ url: app.g ...
- 域渗透基础之Windows 2012创建域控制器
创建备份域控制器 这里就拿windows 2012 R2来当备份域控 如果一个域内有多个域控制器,可以有如下好处. 提高用户登录的效率:如果同时有多台域控制器对客户提供服务,可以分担审核用户登录身份( ...
- Spring Boot2 系列教程(十四)CORS 解决跨域问题
今天和小伙伴们来聊一聊通过CORS解决跨域问题. 同源策略 很多人对跨域有一种误解,以为这是前端的事,和后端没关系,其实不是这样的,说到跨域,就不得不说说浏览器的同源策略. 同源策略是由 Netsca ...