[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 介 ...
随机推荐
- redis常用笔记(第一版)
1.SINTER 说明:多key之间取交集数据 key1 = {a,b,c,d} key2 = {c} key3 = {a,c,e} SINTER key1 key2 key3 = {c} 2.sad ...
- linux分析工具之lsof详解
一.概述 在linux中,所有东西都是以文件的形式存在的,所以我们在linux上的操作都是通过对文件的操作来执行我们所需要的逻辑,比如我们对文件数据的访问,修改,访问网络的连接等,刚好lsof(lis ...
- spring5 源码深度解析----- 事务增强器(100%理解事务)
上一篇文章我们讲解了事务的Advisor是如何注册进Spring容器的,也讲解了Spring是如何将有配置事务的类配置上事务的,实际上也就是用了AOP那一套,也讲解了Advisor,pointcut验 ...
- WebGL简易教程(十一):纹理
目录 1. 概述 2. 实例 2.1. 准备纹理 2.2. 配置纹理 2.3. 使用纹理 3. 结果 4. 参考 1. 概述 在之前的之前的教程<WebGL简易教程(九):综合实例:地形的绘制& ...
- wildfly(JBoss AS)应用服务器快速入门
什么是wildfly JBoss AS 从8版本起名为wildfly.Wildfly是一个开源的基于JavaEE的轻量级应用服务器.可以在任何商业应用中免费使用. WildFly是一个灵活的.轻量的. ...
- LeetCode 第 287 号问题:寻找重复数,一道非常简单的数组遍历题,加上四个条件后感觉无从下手
今天分享的题目来源于 LeetCode 第 287 号问题:寻找重复数. 题目描述 给定一个包含 n + 1 个整数的数组 nums,其数字都在 1 到 n 之间(包括 1 和 n),可知至少存在一个 ...
- Flash XSS漏洞快速上手
0x01 Flash XSS xss一是指执行恶意js,那么为什么说flash xss呢?是因为flash有可以调用js的函数,也就是可以和js通信,因此这些函数如果使用不当就会造成xss.常见的 ...
- Python3的编码整理总结
python3在内存中是用unicode编码方式存储的,所以不能直接储存和传输,要转化为其他编码进行储存和传输. 字符串通过编码转换成字节码,字节码通过解码成为字符串 encode:str --> ...
- 概念理解-Libevent
可移植性: 使用 LibEvent 编写的程序应该在 LibEvent 支持跨越的所有平台上工作,即使没有更好的方法来处理. 非阻塞式IO:LibEvent也应该支持一般的方法使程序可以运行在某些限制 ...
- pycharm中常见错误提示
1.类中定义函方法 PyCharm 提示Method xxx may be 'static': 原因:该方法不涉及对该类属性的操作,编译器建议声明为@staticmethod