swagger 修改dto注解_Swagger 详解
Swagger快速理解
Swagger:The Best APIs are Built with Swagger Tools 。Swagger可以定义一个标准的RESTful风格的API,与语言无关,是一个API的规范。
Swagger官网:http://swagger.io
GitHub地址:https://github.com/swagger-api
这里,提到Swagger就不得不说说Springfox,Springfox是一个开源的API Doc的框架, 它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现。官方定义为: Automated JSON API documentation for API's built with Spring。Swagger和SpringFox到底什么关系呢?
- Swagger Spec 是一个规范。
- Swagger Api 是 Swagger Spec 规范 的一个实现,它支持 jax-rs, restlet, jersey 等等。
- Springfox libraries 是 Swagger Spec 规范 的另一个实现,专注于 spring 生态系统。
- Swagger.js and Swagger-ui 是 javascript 的客户端库,能消费该规范。
- springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ,使得 Spring 服务可以提供服务。
在官网的Tools菜单中,我们会发现里面有很多工具或者系统的介绍。其中我们最常用的两个工具一个是swagger editor、一个是swagger UI。
Swagger Edit
Swagger Edit主要是用来设计,描述API的工具,主要是提供给接口开发人员使用的。swagger editor 编译完接口文档之后呢,会形成一个yaml文件。
Swagger UI
Swagger UI允许任何人 - 无论是您的开发团队还是最终消费者 - 在没有任何实现逻辑的情况下可视化和与API资源交互。 它是从您的OpenAPI规范自动生成的,其可视化文档使后端实现和客户端消费变得容易。
swagger-editor主要是编写api接口文档,但需要配合swagger-ui来查看,里面的代码格式为yaml,但编辑后可以导出yml/json文件
Swagger Edit和Swagger UI 互补性存在
如果只是手动写api文档,人工查看那么就做部署Swagger Edit和Swagger UI就可以了。
通过下面命令下载两个项目:
mkdir swagger
chmod 777 swagger
cd swagger
git clone https://github.com/swagger-api/swagger-editor.git
git clone https://github.com/swagger-api/swagger-ui.git
PS: UI和Edit都是NodeJS的开发,一次需要先安装Nodejs的运行环境。
下载nodejs的安装包,具体要去网站上查看最新版本
wget https://nodejs.org/dist/v6.11.3/node-v6.11.3.tar.gz
tar -zxvf node-v6.11.3.tar.gz
mv node-v6.11.3 /user/local/node
cd /usr/local/node
./configure
make
make install
node -v
先安装http-server
npm install -g http-server
-g表示全局
启动ui和edit
http-server –p 12321 swagger-editor
http-server –p 12421 swagger-ui
cd swagger-ui/dist
vim index.html
进入index.html后,修改如下字段
...
const ui = SwaggerUIBundle({
//url: "http://petstore.swagger.io/v2/swagger.json",
url: "http://127.0.0.1:12321/json/1.json",
dom_id: '#swagger-ui',
...
然后保存后
打开浏览器:
swaggerEdit : http://127.0.0.1:12321
swaggerUI:http://127.0.0.1:12421/dist
Maven插件在原生工程里面快速生产Json的api文件(转自:https://blog.csdn.net/doctor_who2004/article/details/50816208)
在maven工程的pom文件中,放入如下插件:
org.apache.maven.plugins
maven-javadoc-plugin
UTF-8
UTF-8
false
com.github.kongchen
swagger-maven-plugin
false
com.doctor.demo
http,https
petstore.swagger.wordnik.com
/api
Swagger Maven Plugin Sample
v1
This is a sample for swagger-maven-plugin
http://www.github.com/kongchen/swagger-maven-plugin
kongchen@gmail.com
Kong Chen
http://kongch.com
http://www.apache.org/licenses/LICENSE-2.0.html
Apache 2.0
Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"
${basedir}/templates/strapdown.html.hbs
${basedir}/generated/document.html
generated/swagger-ui
compile
generate
Swagger和SpringMVC项目的整合(转自:https://www.cnblogs.com/jtlgb/p/6734177.html)
引入依赖
com.mangofactory
swagger-springmvc
1.0.2
com.mangofactory
swagger-models
1.0.2
com.wordnik
swagger-annotations
1.3.11
com.google.guava
guava
15.0
com.fasterxml.jackson.core
jackson-annotations
2.4.4
com.fasterxml.jackson.core
jackson-databind
2.4.4
com.fasterxml.jackson.core
jackson-core
2.4.4
com.fasterxml
classmate
1.1.0
Swagger配置
Swagger的配置实际上就是自定义一个Config类,通过java编码的方式实现配置。代码如下:
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Created by xiaohui on 2016/1/14.
*/
@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"My Apps API Title",
"My Apps API Description",
"My Apps API terms of service",
"My Apps API Contact Email",
"My Apps API Licence Type",
"My Apps API License URL");
return apiInfo;
}
}
在springmvc的配置文件中加入以下配置即可。
class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
到目前为止,我们已经完成了对所有接口方法的扫描解析功能,那解析得到什么内容呢?这需要我们自定义,自定义操作的对象就是接口方法。先看段代码:
/**
* 根据用户名获取用户对象
* @param name
* @return
*/
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{
UcUser ucUser = ucUserManager.getUserByName(name);
if(ucUser != null) {
ApiResult<UcUser> result = new ApiResult<UcUser>();
result.setCode(ResultCode.SUCCESS.getCode());
result.setData(ucUser);
return result;
} else {
throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");
}
}
上述代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。关于这两个注解的使用,可以参看源码。这样子,Swagger就可以扫描接口方法,得到我们自定义的接口说明内容。
说明: 其中@ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下: @ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”;其他参数可参考源码; @ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”
Swagger-UI配置
Swagger扫描解析得到的是一个json文档,对于用户不太友好。下面介绍swagger-ui,它能够友好的展示解析得到的接口说明内容。
从https://github.com/swagger-api/swagger-ui 获取3.0版本以下,2.0版本以上。其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/WEB-INF/swagger/ 目录下。
修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。比如我的url值为:http://localhost:8083/arrow-api/api-docs
因为swagger-ui项目都是静态资源,restful形式的拦截方法会将静态资源进行拦截处理,所以在springmvc配置文件中需要配置对静态文件的处理方式。
//所有swagger目录的访问,直接访问location指定的目录
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>
OK!大功告成,打开浏览器直接访问swagger目录下的index.html文件,即可看到接口文档说明了
是选择SwaggerUI+EDIT方式还是SpringMVC直接集成,就看你自己的需求了
参考:
https://blog.csdn.net/kinginblue/article/details/78513029 https://www.jianshu.com/p/52acab692a79 https://blog.csdn.net/doctor_who2004/article/details/50816208 https://www.cnblogs.com/jtlgb/p/6734177.html
关注V社北京社,跟踪测试行业技术
swagger 修改dto注解_Swagger 详解相关推荐
- swagger 修改dto注解_Swagger介绍及使用
Swagger介绍及使用 导语: 相信无论是前端还是后端开发,都或多或少地被接口文档折磨过.前端经常抱怨后端给的接口文档与实际情况不一致.后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新.其 ...
- swagger 修改dto注解_Web服务开发:Spring集成Swagger,3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法 在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
- swagger 修改dto注解_一文搞懂Swagger,让你明白用了Swagger的好处!!!
前后端分离缺陷 了解Swagger之前,需要先知道什么是前后端分离 现在的时代 SpringBoot + VUE 以前的时代 SSM + JSP模板引擎====>后端程序员 前后端分离时代 通过 ...
- Spring 注解@Value详解
一.spring(基础10) 注解@Value详解[1] 一 配置方式 @value需要参数,这里参数可以是两种形式: [html] view plaincopy @Value("#{con ...
- @Conditional注解的详解和应用
Spring中@Conditional注解的详解和应用 一.@Conditional注解的作用 二.条件判断在什么时候执行? 2.1 什么是配置类? 2.2 Spring对配置类的处理阶段 2.3 @ ...
- spring之旅第四篇-注解配置详解
spring之旅第四篇-注解配置详解 一.引言 最近因为找工作,导致很长时间没有更新,找工作的时候你会明白浪费的时间后面都是要还的,现在的每一点努力,将来也会给你回报的,但行好事,莫问前程!努力总不会 ...
- Java 注解用法详解——@SuppressWarnings
转自: https://www.cnblogs.com/fsjohnhuang/p/4040785.html Java魔法堂:注解用法详解--@SuppressWarnings 一.前言 编码时我们总 ...
- Java注解(Annotation)详解
转: Java注解(Annotation)详解 幻海流心 2018.05.23 15:20 字数 1775 阅读 380评论 0喜欢 1 Java注解(Annotation)详解 1.Annotati ...
- php mysql修改命令_PHP编程:mysql alter table命令修改表结构实例详解
<PHP编程:mysql alter table命令修改表结构实例详解>要点: 本文介绍了PHP编程:mysql alter table命令修改表结构实例详解,希望对您有用.如果有疑问,可 ...
最新文章
- Kubernetes Eviction Manager工作机制分析
- 【POJ1321棋盘问题】【poj2251Dungeon Master】【poj3278Catch That Cow】【poj1426Find The Multi】
- mysql 层_mysql三层体系
- Swift - 发送消息(文本,图片,文件等)给微信好友或分享到朋友圈
- PHP AJAXFORM提交图片上传并显示图片源代码
- 腾讯面试官这样问我二叉树,我刚好都会 | 原力计划
- Python——numpy排序 求和
- 对象数组 —— 学生信息表
- WinRAR备份技巧 - imsoft.cnblogs
- 刷新了dns后无法访问到mysql_高效刷新DNS缓存 解决网页无法访问
- SHFileOperation删除文件夹
- 用java编写国际象棋
- 计算机网络传输速度单位换算,网络速度单位换算
- 鸿蒙os2021升级日程,消息称华为EMUI 11.1三月上线:更... - @是Ustinian鸭 的微博精选 - 微博国际站...
- 售前工程师的成长---一个老员工的经验之谈(二)(转载)
- StringTemplate模板引擎
- Live555(一)
- ps批量处理dds转tga
- JDBC编程(Java操作数据库 MySQL)
- 单片机c语言sfr,51单片机bit、sbin、sfr、sfr_16区别分析