Springboot+swagger2的接口文档开发
一、创建一个SpringBoot项目
1.
2.
3.
4. 把web里的web选中,SQL里选择自己需要的,点击next
二、创建各项所需的controller,configure等
1. 项目布局
2. 引入的包
<!-- swagger2所用的包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency> <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
3. swagger配置类,配置类有多种方法,试过使用.apis(RequestHandlerSelectors.basePackage("com.txp.controller"))的方法扫描controller包的位置,结果访问swagger页面的时候显示不出来,应该是没有扫描到,所以使用了下面的方法,即所有使用@ApiOperation注解的类都会被扫描
package com.txp.swagger2.configue; import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; // 用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。
@Configuration
@EnableSwagger2
public class Swagger { @Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
} private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档") // 页面标题
.description("简单优雅的restful风格") // 创建人
.termsOfServiceUrl("")
.version("1.0")// 版本号
.description("测试springboot结合swagger2")// 描述
.build();
}
}
4. 实体类User,JsonResult
package com.txp.swagger2.configue; import java.util.Date; public class User { private int id;
private String username;
private int age;
private Date ctm; public int getId() {
return id;
} public void setId(int id) {
this.id = id;
} public String getUsername() {
return username;
} public void setUsername(String username) {
this.username = username;
} public int getAge() {
return age;
} public void setAge(int age) {
this.age = age;
} public Date getCtm() {
return ctm;
} public void setCtm(Date ctm) {
this.ctm = ctm;
}
}
package com.txp.swagger2.configue; public class JsonResult { private String status = null; private Object result = null; public String getStatus() {
return status;
} public void setStatus(String status) {
this.status = status;
} public Object getResult() {
return result;
} public void setResult(Object result) {
this.result = result;
}
}
5. UserController类
package com.txp.swagger2.controller; import com.txp.swagger2.configue.JsonResult;
import com.txp.swagger2.configue.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController; import java.util.*; @RestController
public class UserController { static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer,User>()); @ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id",value = "用户ID",required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "users",method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserById(){
JsonResult r = new JsonResult();
try{
List<User> userList = new ArrayList<User>(users.values());
r.setResult(userList);
r.setStatus("ok");
} catch (Exception e){
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
} return ResponseEntity.ok(r);
}
}
6. 启动类配置
package com.txp.swagger2; import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
// 加上注解@EnableSwagger2 表示开启Swagger
@EnableSwagger2
public class Swagger2Application { public static void main(String[] args) { SpringApplication.run(Swagger2Application.class, args);
} }
三、结果
四、Swagger注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数
补充常用参数、属性
备注(各参数意义):
作用范围 API 使用位置
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上
@ApiImplicitParam参数:
属性 取值 作用
paramType 查询参数类型
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST
dataType 参数的数据类型 只作为标志说明,并没有实际验证
Long
String
name 接收参数名
value 接收参数的意义描述
required 参数是否必填
true 必填
false 非必填
defaultValue 默认值
Springboot+swagger2的接口文档开发的更多相关文章
- swagger2的接口文档
以前见过一个swagger2的接口文档,特别好用,好看,对接口中入参描述的很详细:适合用于项目的开发 后来自己做项目的时候,没有找到这个swagger版本 <dependency> < ...
- Springboot集成swagger2生成接口文档
[转载请注明]: 原文出处:https://www.cnblogs.com/jstarseven/p/11509884.html 作者:jstarseven 码字挺辛苦的..... 一 ...
- SpringBoot 如何生成接口文档,老鸟们都这么玩的!
大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反响都还不错,果然大家还是对SpringBoot比较感兴趣.那今天我们就带来老鸟系列的第三篇:集成Swagger接口文档以 ...
- springboot + swagger2 生成api文档
直接贴代码: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-sw ...
- SpringFox swagger2 and SpringFox swagger2 UI 接口文档生成与查看
依赖: <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency ...
- Springboot swagger2 导出api文档
具体导出的代码,参考了:http://www.spring4all.com/article/699 导出前,首先需要配置好swagger2,参见 https://www.cnblogs.com/yan ...
- SpringBoot 使用Swagger2打造在线接口文档(附汉化教程)
原文地址: https://www.jianshu.com/p/7e543f0f0bd8 SpringBoot + Swagger2 UI界面-汉化教程 1.默认的英文界面UI 想必很多小伙伴都曾经使 ...
- springboot+swagger接口文档企业实践(上)
目录 1.引言 2.swagger简介 2.1 swagger 介绍 2.2 springfox.swagger与springboot 3. 使用springboot+swagger构建接口文档 3. ...
- 接口开发-集成接口文档(swagger)
在正式进入主题之前,先说说实际工作中遇到的问题.不算是传统的原生APP开发,还是眼下的H5混合开发,只要是需要前后端通过接口配合的,往往都存在几个普遍的问题 (1)接口文档谁来写,尤其是跨部门,并且, ...
随机推荐
- zabbix-agent端自定义监控项(free -m)服务器内存使用率
Agent端操作 [root@agent ~]# vim /usr/local/zabbix/etc/zabbix_agentd.conf 末行追加 UserParameter=memory_user ...
- ES modules
注意:这篇文章讲的是正经的es module规范 及浏览器的实现!webpack项目中es module会被parse成commonjs,和这个没大关系! 总结: ES模块加载的主要过程: 构造 —— ...
- PHP算法之四大基础算法
前言 虽然工作中,你觉得自己并没有涉及到算法这方面的东西,但是算法是程序的核心,一个程序的好与差,关键是这个程序算法的优劣,所以对于冒泡排序.插入排序.选择排序.快速排序这四种基本算法,我想还是要掌握 ...
- Vue-router入门
1.npm install vue-router --save-dev 安装路由包,在安装脚手架时实际上可以直接安装 2.解读核心文件 router/index.js文件 import Vue fro ...
- tp 在Nginx上各种404
对于ThinkPHP的URL访问路劲如:http://域名/index.php/Index/BlogTest/read,原先的Nginx的是不支持的pathinfo路劲的,导致你在thinkPHP5上 ...
- 数据库范式1NF 2NF 3NF BCNF(实例)通俗易懂的讲解
[转] 数据库范式1NF 2NF 3NF BCNF(实例)通俗易懂的讲解 本文对大多数初学数据库原理的同学绝对是个大福利,哈哈,完完整整的看完此篇博文一定能够清晰地理解数据库的四大范式. ...
- 楼宇自控-RS232\RS485\RS422
1.rs-232-c rs-232-c是美国电子工业协会eia(electronic industry association)制定的一种串行物理接口标准.rs是英文"推荐标准"的 ...
- tddl
淘宝根据自己的业务特点开发了TDDL(Taobao Distributed Data Layer 外号:头都大了 ?_Ob)框架,主要解决了分库分表对应用的透明化以及异构数据库之间的数据复制,它是一个 ...
- 低效能的”where1=1”
网上有不少人提出过类似的问题:"看到有人写了where 1=1这种sql,究竟是什么意思?".事实上使用这种使用方法的开发者一般都是在使用动态数组的sql. 让我们想象例如以下的场 ...
- [博弈] hdu 3683 Gomoku
题意: 两个人下五子棋.给你现有棋盘,推断在三步之内的胜负情况. 输出分为几种. 1.棋盘不合法 2.黑或白在第一步赢下在(x,y)点,多个输出x最小的.y最小的. 3.输在第二步 4.黑或白在第三步 ...