SpringMVC 开发 — 使用 Swagger 搭建接口请求页面
(点击
上方公众号
,可快速关注)
来源:MSSQL123,
blog.csdn.net/chenyufeng1991/article/details/69201353
Swagger是一款RESTful接口的文档在线自动生成模板和页面,使用和平台以及语言无关。目前在很多公司以及实际项目中大量用到。可以把Swagger理解为接口文档,后台写好的代码可以直接生成前端接口文档页面,接口调用这可以通过这个页面发送接口请求,进行接口测试或调用。使用起来非常方便。使用了Swagger之后,就不需要再去维护其他的接口文档了,节省了很多的成本。本文使用的项目案例上传至 http://github.com/chenyufeng1991/StartSpringMVC.git 。本文将会来介绍如何搭建一个完整的Swagger框架。Swagger的官方地址为:http://swagger.io/。一个简答的Swagger页面如下图所示:
(1)Swagger在Github上的地址为:http://github.com/swagger-api/swagger-ui 。大家可以下载该项目,然后把dist目录下的所有内容都加入到自己项目的webapp目录下。大家也可以下载我的StartSpringMVC项目,把webapp目录下的css、images、lib、index.html和swagger-ui.js导入到自己的项目中即可。其中显示的前端页面就是index.html.
(2)然后需要在项目中新加一个类,作为swagger的配置文件,我在StartSpringMVC中的类是“CustomJavaPluginConfig”,该类的实现如下:
@Configuration
@EnableWebMvc
@EnableSwagger
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
private SpringSwaggerConfig springSwaggerConfig;
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
@Bean
public SwaggerSpringMvcPlugin customImplementation() {
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo()).includePatterns(".*")
.useDefaultResponseMessages(false)
// .pathProvider(new GtPaths())
.apiVersion("0.1").swaggerGroup("user");
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo("我的RESTful接口平台",
"提供详细的后台所有Restful接口", "http://blog.csdn.net/chenyufeng1991",
"yufengcode@gmail.com", "乞力马扎罗的雪-博客", "http://blog.csdn.net/chenyufeng1991");
return apiInfo;
}
@Override
public void configureDefaultServletHandling(
DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
class GtPaths extends SwaggerPathProvider {
@Override
protected String applicationPath() {
return "/restapi";
}
@Override
protected String getDocumentationPath() {
return "/restapi";
}
}
}
(3)对于一个实体模型,需要使用swagger去标识。如下面的Student模型,其中的@ApiModel、@ApiModelProperty都是属于Swagger的注解。如果需要在接口中返回模型对象,则需要使用以下的方式去注解。
@ApiModel(value = "http://www.gunmi.cn/v/学生对象", description = "student")
public class Student {
@ApiModelProperty(value = "http://www.gunmi.cn/v/姓名", required = true)
String name;
@ApiModelProperty(value = "http://www.gunmi.cn/v/年龄", required = true)
String age;
public Student(String name, String age) {
this.name = name;
this.age = age;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
}
(4)在进行接口设计的Controller中,同样需要使用Swagger注解。其中下面的@Api、@ApiOperaction、@Apiparam都是Swagger注解,其中@Api表示这是一个需要Swagger表示的类;@ApiOperaction表示这是一个需要Swagger修饰的接口,其中表明了请求方式、说明等信息。@ApiParam表示该接口输入的参数,value是参数的值说明,required表示该参数是否是必须的。
@Api(value = "http://www.gunmi.cn/v/football", description = "足球", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("football")
public class FootballController {
@ApiOperation(value = "http://www.gunmi.cn/v/用户登录注册", notes = "用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "http://www.gunmi.cn/v/user", method = RequestMethod.GET)
public List<Student> foo(
@ApiParam(value = "http://www.gunmi.cn/v/用户名", required = true) @RequestParam String name,
@ApiParam(value = "http://www.gunmi.cn/v/年龄", required = true) @RequestParam String age
) {
//获取请求的参数,需要和链接中的参数名一致
//推荐使用HttpServletRequest的方式来获取参数,GET、POST的参数都可以接收
List<Student> list = new ArrayList<Student>();
Student student = new Student(name, age);
Student student1 = new Student(name + name, age + age);
list.add(student);
list.add(student1);
return list;
}
@ApiOperation(value = "http://www.gunmi.cn/v/用户登录注册2", notes = "用户2", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "http://www.gunmi.cn/v/customer/login", method = RequestMethod.POST)
public String foo2(
@ApiParam(value = "http://www.gunmi.cn/v/用户名", required = true) @RequestParam String name
) {
return name;
}
}
(5)重要的是,要在pom.xml中加入swagger的依赖:
<!-- Swagger-mvc -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
(6)完成后的运行界面如下图所示。大家可以根据自己的实际需求自定义页面元素。
看完本文有收获?请转发分享给更多人
关注「ImportNew」,提升Java技能
- 【生活】这个小家电几乎每家都有,使用不当很危险!
- “提速降费”的三大关注
- 冯仑:房地产进入后开发时代,转型、布局都得趁早
- 无辜的开发商:没人买,没法卖,时也,命也,专家:抛房无人接盘
- 三家房企赚了1.5万亿,因为开发商把负债转移到购房者身上!
- 房产离开贷款将出现什么情况,买房者想贷款,开发商依靠贷款
- 开发区47个项目 申报这项资助
- 房价高责怪开发商?2018年,任志强的预言会实现吗?
- 买房不要买这4种房子,中了赶紧找开发商退钱,等入住才知吃大亏
- 【图说科普】陕西省科协:脱贫攻坚政策