【工具】Swagger2写接口注释
一、遇到的问题
作为一名coder,经常需要向别人提供接口,或者调用别人的接口。于是就有了接口参数是什么意思,要怎么传参数,返回值是什么意思……有多少调用方,就会有多少人来询问这些参数。如果是长时间之后,自己或许都不知道这些参数是什么意思。于是维护接口文档便成了一项必不可少的工作,维护文档也有很多问题:
- 如果手工写会很费劲
- 接口变更后可能会忘了同步文档
- ……
二、Swagger配置
Swagger(官方文档)可以快速帮助实现接口api的维护与简单测试。
a、引入maven依赖包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
b、配置Swagger
@Configuration
@EnableSwagger2
@Profile("dev")
public class SwaggerConfig {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "api.doc.demo.controller";
public static final String VERSION = "1.0.0"; @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/**api接口包扫描路径*/
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
/**可以根据url路径设置哪些请求加入文档,忽略哪些请求*/
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
/**设置文档的标题*/
.title("Swagger2 接口文档示例")
/**设置文档的描述*/
.description("更多内容请关注:http://www.abc.com")
/**设置文档的联系方式*/
.contact(new Contact("create by XXX", "http://www.abc.com", "xxxx.@xxx.com"))
/**设置文档的License信息->1.3 License information*/
.termsOfServiceUrl("www.abc.com")
.license("xxx")
.licenseUrl("http://www.xxx.com")
/**设置文档的版本信息-> 1.1 Version information*/
.version(VERSION)
.build();
}
}
c、常用注解
- @ApiOperation : api说明
@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")
@RequestMapping(value="/getList", method= RequestMethod.GET)
public List<UserModel> getUserList() {
return getDemoList();
}
- @ApiResponses :默认Response的基础上增加新的Response说明
- @ApiImplicitParam : 描述接口参数
@ApiImplicitParam(name = "userId",value = "用户ID",dataType = "int",paramType = "path")
- @ApiImplicitParams : 多个参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),
@ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
- @ApiModel : model属性
@ApiModel(value = "user", description = "user对象")
public class UserModel {
@ApiModelProperty(value = "ID", dataType = "Integer", required = true)
private Integer userId;
@ApiModelProperty(value = "用戶名", dataType = "String")
private String userName;
@ApiModelProperty(value = "性別", dataType = "Integer", allowableValues = "0,1,2")
private Integer sex;
}
这样就可以通过访问 http://localhost:8080/swagger-ui.html 看到接口API调用说明。demo
【工具】Swagger2写接口注释的更多相关文章
- Java的LockSupport工具,Condition接口和ConditionObject
在之前我们文章(关于多线程编程基础和同步器),我们就接触到了LockSupport工具和Condition接口,之前使用LockSupport工具来唤醒阻塞的线程,使用Condition接口来实现线程 ...
- Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...
- 在Eclipse中怎样写Java注释
java中的注释分为实现注释和文档注释 实现注释就是那些/……../和//……的注释,是注释程序用的,文档注释是/*……./的注释,是用来生成javadoc的.设置方法如下: 1.打开Eclipse的 ...
- 【百度地图API】如何在地图上添加标注?——另有:坐标拾取工具+打车费用接口介绍
原文:[百度地图API]如何在地图上添加标注?--另有:坐标拾取工具+打车费用接口介绍 摘要: 在这篇文章中,你将学会,如何利用百度地图API进行标注.如何使用API新增的打车费用接口. ------ ...
- 前端必备之Node+mysql+ejs模版如何写接口
前端必备之Node+mysql+ejs模版如何写接口 这星期公司要做一个视频的后台管理系统, 让我用Node+mysql+ejs配合写接口, 周末在家研究了一下, 趁还没来具体需求把研究内容在这里分享 ...
- node+pm2+express+mysql+sequelize来搭建网站和写接口
前面的话:在这里已经提到了安装node的方法,node是自带npm的.我在技术中会用es6去编写,然后下面会分别介绍node.pm2.express.mysql.sequelize.有少部分是摘抄大佬 ...
- Springboot集成swagger2生成接口文档
[转载请注明]: 原文出处:https://www.cnblogs.com/jstarseven/p/11509884.html 作者:jstarseven 码字挺辛苦的..... 一 ...
- Java后端开发工作 - 写接口
我在公司的工作内容是,对于一个BS应用,负责服务器端开发工作,Java语言.与前端开发人员合作,最终提供给前端RESTFUL接口,保证页面正常响应. 经验之谈 一个接口可以理解为一个业务逻辑,一个业务 ...
- 「快学springboot」16.让swagger帮忙写接口文档
swagger简介 官方的介绍 THE WORLD'S MOST POPULAR API TOOLING Swagger is the world's largest framework of API ...
随机推荐
- JSON-Server 安装
在后台还没给接口之前,使用JSON-Server搭建一台JSON服务器,将接口要返回的数据放在json文件里面.然后请求这些数据,这样我们可以先做一些东西,等后台接口好了之后直接替换就可以了,不必一直 ...
- angular2+ 引用layDate日期选择插件
layDate日期选择插件使用npm安装好像是行不通的,但angular2+的日期选择控件库又不能够支持时分秒的选择 在angular项目中引用layDate 1. 首先官网下载layDate独立版, ...
- 160309、Spring AOP操作action时无法注入,报空指针错误
今天帮同事看个问题,action注入失败,代码没问题,主要是stuts2权限移交的问题,特此记录一下 Spring AOP操作action时无法注入,报NullPointer异常 当使用Spring ...
- wf-删除所选
w框架-结合用户的不同点击路径,提交正确的id集合. <table class="table"> <tr> <td></td> &l ...
- Python多股票同周期可视化
import warnings warnings.filterwarnings("ignore") import numpy as np import pandas as pd i ...
- HDFS基本操作的API
一.从hdfs下载文件到windows本地: package com.css.hdfs01; import java.io.IOException; import java.net.URI; impo ...
- 前端构建工具gulpjs的使用介绍及技巧(一)
原文链接:http://www.cnblogs.com/2050/p/4198792.html gulpjs是一个前端构建工具,与gruntjs相比,gulpjs无需写一大堆繁杂的配置参数,API也非 ...
- 基于flask的代码上传
from flask import Flask,Blueprint,request,render_template from flask import current_app as app from ...
- JSP学习(第二课)
把GET方式改为POST在地址栏上就不会显示. 发现乱码了,设置编码格式(这个必须和reg.jsp中page的charset一致): 但是注意了!我们传中文名,就会乱码: 通过get方式提交的请求无 ...
- js 屏蔽浏览器右键菜单
<script type="text/javascript"> function doNothing(){ window.event.returnValue=false ...