hwf453
/
weather
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd9a9b6ec7c'
${ noResults }
weather/swagger3/SpringBoot整合Swagger3生成接口文档 ...

147 lines
113 KiB
HTML
Raw Normal View History Unescape Escape

Initial commit
2 years ago
<!DOCTYPE html>
<!-- saved from url=(0038)https://zhuanlan.zhihu.com/p/161947638 -->
<html lang="zh" data-hairline="true" data-theme="light" data-react-helmet="data-theme" style=""><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>SpringBoot整合Swagger3生成接口文档 - 知乎</title><meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1"><meta name="renderer" content="webkit"><meta name="force-rendering" content="webkit"><meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"><meta name="google-site-verification" content="FTeR0c8arOPKh8c5DYh_9uu98_zJbaWw53J-Sch9MTg"><meta data-react-helmet="true" name="keywords" content="Swagger,前后端分离,软件接口"><meta data-react-helmet="true" name="description" content="前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，在需求不断变更的环境下，手动编写文档的效率实在太低。与swagger2相比新版的swagger3配置更少，使用…"><meta data-react-helmet="true" property="og:title" content="SpringBoot整合Swagger3生成接口文档"><meta data-react-helmet="true" property="og:url" content="https://zhuanlan.zhihu.com/p/161947638"><meta data-react-helmet="true" property="og:description" content="前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，在需求不断变更的环境下，手动编写文档的效率实在太低。与swagger2相比新版的swagger3配置更少，使用…"><meta data-react-helmet="true" property="og:image" content="https://pic4.zhimg.com/v2-c7e04b00af3237756dac849b8213ee6d_720w.jpg?source=172ae18b"><meta data-react-helmet="true" property="og:type" content="article"><meta data-react-helmet="true" property="og:site_name" content="知乎专栏"><link data-react-helmet="true" rel="apple-touch-icon" href="https://static.zhihu.com/heifetz/assets/apple-touch-icon-152.a53ae37b.png"><link data-react-helmet="true" rel="apple-touch-icon" href="https://static.zhihu.com/heifetz/assets/apple-touch-icon-152.a53ae37b.png" sizes="152x152"><link data-react-helmet="true" rel="apple-touch-icon" href="https://static.zhihu.com/heifetz/assets/apple-touch-icon-120.bbce8f18.png" sizes="120x120"><link data-react-helmet="true" rel="apple-touch-icon" href="https://static.zhihu.com/heifetz/assets/apple-touch-icon-76.cbade8f9.png" sizes="76x76"><link data-react-helmet="true" rel="apple-touch-icon" href="https://static.zhihu.com/heifetz/assets/apple-touch-icon-60.8f6c52aa.png" sizes="60x60"><link crossorigin="" rel="shortcut icon" type="image/x-icon" href="https://static.zhihu.com/heifetz/favicon.ico"><link crossorigin="" rel="search" type="application/opensearchdescription+xml" href="https://static.zhihu.com/heifetz/search.xml" title="知乎"><link rel="dns-prefetch" href="https://static.zhimg.com/"><link rel="dns-prefetch" href="https://pic1.zhimg.com/"><link rel="dns-prefetch" href="https://pic2.zhimg.com/"><link rel="dns-prefetch" href="https://pic3.zhimg.com/"><link rel="dns-prefetch" href="https://pic4.zhimg.com/"><style>
.u-safeAreaInset-top {
height: constant(safe-area-inset-top) !important;
height: env(safe-area-inset-top) !important;
}
.u-safeAreaInset-bottom {
height: constant(safe-area-inset-bottom) !important;
height: env(safe-area-inset-bottom) !important;
}
</style><link href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.app.216a26f4.0e6b2f0ed841f5b3d751.css" crossorigin="" rel="stylesheet"><script defer="" crossorigin="anonymous" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/init.js" data-sentry-config="{&quot;dsn&quot;:&quot;https://2d8d764432cc4f6fb3bc78ab9528299d@crash2.zhihu.com/1224&quot;,&quot;sampleRate&quot;:0.1,&quot;release&quot;:&quot;2230-ac2013d2&quot;,&quot;ignoreErrorNames&quot;:[&quot;NetworkError&quot;,&quot;SecurityError&quot;],&quot;ignoreErrors&quot;:[&quot;origin message&quot;,&quot;Network request failed&quot;,&quot;无法 fetch&quot;,&quot;这个系统不支持该功能。&quot;,&quot;Can&#39;t find variable: webkit&quot;,&quot;Can&#39;t find variable: $&quot;,&quot;内存不足&quot;,&quot;out of memory&quot;,&quot;DOM Exception 18&quot;,&quot;The operation is insecure&quot;,&quot;[object Event]&quot;,&quot;[object FileError]&quot;,&quot;[object DOMError]&quot;,&quot;[object Object]&quot;,&quot;拒绝访问。&quot;,&quot;Maximum call stack size exceeded&quot;,&quot;缺少 JavaScript 对象&quot;,&quot;componentWillEnter&quot;,&quot;componentWillLeave&quot;,&quot;componentWillAppear&quot;,&quot;getInlineStyleAt&quot;,&quot;getCharacterList&quot;,&quot;draft-js&quot;,&quot;UploadError&quot;,{},{},{},&quot;Non-Error exception captured&quot;],&quot;whitelistUrls&quot;:[&quot;static.zhihu.com&quot;]}"></script><style data-emotion-css="1cd9gw4">.css-1cd9gw4{margin-left:.3em;}</style><style data-emotion-css="qbubgm">.css-qbubgm{margin-left:0;}</style><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.zswsdid.12908df265f9866a0ae6.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.user-hover-card.216a26f4.f19b464299cd4889eeb6.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.user-hover-card.b6d93e063dcf3ba6b80a.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.Labels.216a26f4.7d19d2afdc588e36471f.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.Labels.b0d8f29f758d69618b0f.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.GoodsRecommendGoodsCardList.216a26f4.fa8ead9ef18009727ea4.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.GoodsRecommendGoodsCardList.a3153a44a3e3e2e0c7aa.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.modals.216a26f4.37f34e5eadb9da06be9d.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.modals.c4da0eb29cd568402080.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.comments-modals.216a26f4.953f6e8064d7f947f0da.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.comments-modals.85cdd6e27cb828157e15.js" crossorigin="anonymous"></script><style data-emotion="css"></style><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.signflow.216a26f4.bd7f666221e7000b679c.css" crossorigin="anonymous"><script charset="utf-8" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.signflow.eb4f90e71b6b6764028d.js" crossorigin="anonymous"></script><link rel="stylesheet" type="text/css" href="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/column.richinput.216a26f4.5995aa589198d37c53ce.css" crossorigin="anonymous"><script charset="ut
&lt;groupId&gt;io.springfox&lt;/groupId&gt;
&lt;artifactId&gt;springfox-boot-starter&lt;/artifactId&gt;
&lt;version&gt;3.0.0&lt;/version&gt;
&lt;/dependency&gt;
</code></pre></div><h2>二、Application上面加入@EnableOpenApi注解</h2><div class="highlight"><pre><code class="language-text">@EnableOpenApi
@SpringBootApplication
@MapperScan(basePackages = {"cn.ruiyeclub.dao"})
public class Swagger3Application {
public static void main(String[] args) {
SpringApplication.run(Swagger3Application.class, args);
}
}
</code></pre></div><h2>三、Swagger3Config的配置</h2><div class="highlight"><pre><code class="language-text">@Configuration
public class Swagger3Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("更多请咨询服务开发者Ray。")
.contact(new Contact("Ray。", "http://www.ruiyeclub.cn", "ruiyeclub@foxmail.com"))
.version("1.0")
.build();
}
}
</code></pre></div><h2>四、Swagger注解的使用说明</h2><div class="highlight"><pre><code class="language-text">@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --&gt; 请求参数的获取：@RequestHeader
· query --&gt; 请求参数的获取：@RequestParam
· path（用于restful接口）--&gt; 请求参数的获取：@PathVariable
· div（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
</code></pre></div><p>Controller层的配置：</p><div class="highlight"><pre><code class="language-text">@Api(tags = "用户信息管理")
@RestController
@RequestMapping("userRecord")
public class UserRecordController extends ApiController {
/**
* 服务对象
*/
@Resource
private UserRecordService userRecordService;
/**
* 分页查询所有数据
* @param page 分页对象
* @param userRecord 查询实体
* @return 所有数据
*/
@ApiOperation("分页查询所有数据")
@GetMapping("page")
public R selectAll(Page&lt;UserRecord&gt; page, UserRecord userRecord) {
return success(this.userRecordService.page(page, new QueryWrapper&lt;&gt;(userRecord)));
}
/**
* 通过主键查询单条数据
* @param id 主键
* @return 单条数据
*/
@ApiOperation("通过主键查询单条数据")
@GetMapping("{id}")
public R selectOne(@PathVariable Serializable id) {
return success(this.userRecordService.getById(id));
}
/**
* 新增数据
* @param userRecord 实体对象
* @return 新增结果
*/
@ApiOperation("新增数据")
@PostMapping("insert")
public R insert(@RequestBody UserRecord userRecord) {
return success(this.userRecordService.save(userRecord));
}
/**
* 修改数据
* @param userRecord 实体对象
* @return 修改结果
*/
@ApiOperation("修改数据")
@PutMapping("update")
public R update(@RequestBody UserRecord userRecord) {
return success(this.userRecordService.updateById(userRecord));
}
/**
* 删除数据
* @param idList 主键结合
* @return 删除结果
*/
@ApiOperation("删除数据")
@DeleteMapping("delete")
public R delete(@RequestParam("idList") List&lt;Long&gt; idList) {
return success(this.userRecordService.removeByIds(idList));
}
}
View Code</code></pre></div><p>五、Swagger界面效果</p><p class="ztext-empty-paragraph"><br></p><figure data-size="normal"><noscript><img src="https://pic3.zhimg.com/v2-8fac9dc146b0af4deaebf14e5d68148e_b.jpg" data-caption="" data-size="normal" data-rawwidth="550" data-rawheight="299" class="origin_image zh-lightbox-thumb" width="550" data-original="https://pic3.zhimg.com/v2-8fac9dc146b0af4deaebf14e5d68148e_r.jpg"/></noscript><img src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/v2-8fac9dc146b0af4deaebf14e5d68148e_720w.jpg" data-caption="" data-size="normal" data-rawwidth="550" data-rawheight="299" class="origin_image zh-lightbox-thumb lazy" width="550" data-original="https://pic3.zhimg.com/v2-8fac9dc146b0af4deaebf14e5d68148e_r.jpg" data-actualsrc="https://pic3.zhimg.com/v2-8fac9dc146b0af4deaebf14e5d68148e_b.jpg" data-lazy-status="ok"></figure><p class="ztext-empty-paragraph"><br></p><p>Swagger的访问路径由port/swagger-ui.html改成了 port/swagger-ui/ 或port/swagger-ui/index.html ，项目演示代码在 springboot-swagger</p><p class="ztext-empty-paragraph"><br></p><a target="_blank" href="https://link.zhihu.com/?target=https%3A//shimo.im/docs/ILL3EcF2XlkwUMoO/" data-draft-node="block" data-draft-type="link-card" data-image="https://pic4.zhimg.com/v2-2193dee59de82a8eeaa77f9ed0c65a63_180x120.jpg" data-image-width="960" data-image-height="600" class="LinkCard old LinkCard--hasImage" data-za-detail-view-id="172"><span class="LinkCard-backdrop" style="background-image:url(https://pic4.zhimg.com/v2-2193dee59de82a8eeaa77f9ed0c65a63_180x120.jpg)"></span><span class="LinkCard-content"><span class="LinkCard-text"><span class="LinkCard-title" data-text="true">Java进阶：架构设计、并发编程等核心知识、电子书、视频、面试题等免费获取</span><span class="LinkCard-meta"><span style="display:inline-flex;align-items:center">​<svg class="Zi Zi--InsertLink" fill="currentColor" viewBox="0 0 24 24" width="17" height="17"><path d="M13.414 4.222a4.5 4.5 0 1 1 6.364 6.364l-3.005 3.005a.5.5 0 0 1-.707 0l-.707-.707a.5.5 0 0 1 0-.707l3.005-3.005a2.5 2.5 0 1 0-3.536-3.536l-3.005 3.005a.5.5 0 0 1-.707 0l-.707-.707a.5.5 0 0 1 0-.707l3.005-3.005zm-6.187 6.187a.5.5 0 0 1 .638-.058l.07.058.706.707a.5.5 0 0 1 .058.638l-.058.07-3.005 3.004a2.5 2.5 0 0 0 3.405 3.658l.13-.122 3.006-3.005a.5.5 0 0 1 .638-.058l.069.058.707.707a.5.5 0 0 1 .058.638l-.058.069-3.005 3.005a4.5 4.5 0 0 1-6.524-6.196l.16-.168 3.005-3.005zm8.132-3.182a.25.25 0 0 1 .353 0l1.061 1.06a.25.25 0 0 1 0 .354l-8.132 8.132a.25.25 0 0 1-.353 0l-1.061-1.06a.25.25 0 0 1 0-.354l8.132-8.132z"></path></svg></span>shimo.im</span></span><span class="LinkCard-imageCell"><img class="LinkCard-image LinkCard-image--horizontal" alt="图标" src="./SpringBoot整合Swagger3生成接口文档 - 知乎_files/v2-2193dee59de82a8eeaa77f9ed0c65a63_180x120.jpg"></span></span></a><p><b><i>点击领取学习资料</i></b></p></div></div><div class="ContentItem-time">发布于 2020-07-20</div><div class="Post-topicsAndReviewer"><div class="TopicList Post-Topics"><div class="Tag Topic" data-za-detail-view-path-module="TopicItem" data-za-extra-module="{&quot;card&quot;:{&quot;content&quot;:{&quot;type&quot;:&quot;Topic&quot;,&quot;token&quot;:&quot;20080742&quot;}}}"><span class="Tag-content"><a class="TopicLink" href="https://www.zhihu.com/topic/20080742" target="_blank"><div class="Popover"><div id="Popover1-toggle" aria-haspopup="true" aria-expanded="false" aria-owns="Popover1-content">Swagger</div></div></a></span></div><div class="Tag Topic" data-za-detail-view-path-module="TopicItem" data-za-extra-module="{&quot;card&quot;:{&quot;content&quot;:{&quot;type&quot;:&quot;Topic&quot;,&quot;token&quot;:&quot;20043499&quot;}}}"><span class="Tag-content"><a class="TopicLink" href="https://www.zhihu.com/topic/20043499" target="_blank"><div class="Popover"><div id="Popover2-toggle" aria-haspopup="true" aria-expanded="false" aria-owns="Popover2-content">前后端分离</div></div></a></span></div><div class="Tag Topic" data-za-detail-view-path-module="TopicItem" d