其实与spring+springmvc+mybatis集成swagger没什么区别,只是之前写的太不好了,所以这次决定详细写。
提到swagger不得不提rest,rest是一种架构风格,里面有对不同的资源有不同的请求标识。例如PUT,POST,GET,DELETE,OPTIONS,HEAD,PATCH等。
对于技术的初学,最好的话还是建议去官网,官网最详细也最权威,虽然不少博客对此有挺好的解说,但还是强烈建议去官网,不要求仔仔细细阅读,至少读个大概。
对于目前,有人要问我swagger能做什么,可以解决什么问题?我不能详细的给你一一道来,因为我对此不是十分精通,至少它解决了我两个问题,第一个,接口文档的编写,之前通过接口文档,但是随着后续接口是越来越多,文档也需要变来变去,本来就力不从心,又是一大堆接口要写,又是文档要写,swagger就可以轻松的解决这个问题,通过swagger注解可以让安卓方面清楚看到这个接口的作用是什么,还可以在线测试,返回数据;第二个问题,就是接口管理,通过swagger我可以根据接口类型,比如有用户管理,文章管理等等,我通过swagger注解可以轻松的给它们分累以方便我下次编写或修改。
pom依赖:
<!-- swagger --> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>1.0.2</version> </dependency>
就是上述这一个,我的MP实战系列(一)中pom就有这个。
要集成swagger导入上述的依赖之外,还要添加一个类并在springmvc.xml中配置
<!-- 将 springSwaggerConfig加载到spring容器 --> <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" /> <!-- 将自定义的swagger配置类加载到spring容器 --> <bean class="com.lms.swagger.SwaggerConfig" />
SwaggerConfig.java
package com.lms.swagger; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; 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; @EnableSwagger 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( "springmvc搭建swagger", "spring-API swagger测试", "My Apps API terms of service", "19****81**@qq.com", "web app", "My Apps API License URL"); return apiInfo; } }
上述的步骤可以解说为:导入swagger-springmvc依赖并在springmvc.xml中配置,编写对应的配置类,就算完成springmvc集成swagger的第一大步了,当然这还远远不够,还需要导入一个很重要的那就是swagger相关的类库(js,css等之类的)
可从github上下载:https://github.com/swagger-api/swagger-ui
本人使用的是2.2.10版本
下载完成后,进行解压,解压后的目录为:
将红色标记处的dist文件夹里面的js,css之类的全部导入webapp目录下
dist目录图为:
index.html中有一处地址需要修改
将此处的url替换为自己本地项目地址,例如http://localhost:8080/blog/api-docs
然后在对应的Controller添加如下注解,此处以我博客系统的UserController作为演示示例:
package com.blog.controller; import java.util.HashMap; import java.util.Map; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.http.MediaType; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.ResponseBody; import org.springframework.web.bind.annotation.RestController; import com.alibaba.fastjson.JSON; import com.baomidou.mybatisplus.mapper.EntityWrapper; import com.blog.entity.UserEntity; import com.blog.service.UserService; import com.wordnik.swagger.annotations.Api; import com.wordnik.swagger.annotations.ApiImplicitParam; import com.wordnik.swagger.annotations.ApiImplicitParams; import com.wordnik.swagger.annotations.ApiOperation; import com.wordnik.swagger.annotations.ApiParam; /** * * * @author youcong * @email ${email} * @date 2018-04-21 15:27:01 */ @Api(value="博客用户管理") @RestController @RequestMapping("user") public class UserController { @Autowired private UserService userService; @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE) @PostMapping(value="/getById") public String list( @ApiParam(value = "用户ID", required = true) @RequestParam Integer id) { EntityWrapper<UserEntity> wrapper = new EntityWrapper<UserEntity>(); wrapper.eq("user_id", id); UserEntity userEntity = userService.selectOne(wrapper); return JSON.toJSONString(userEntity); } }
效果图如下:
可在线进行接口测试,对于后台开发者来说,之前没有使用swagger通常使用postMan测试post请求,现在使用了swagger方便管理接口,又可以在线测试。
swagger常用注解:
最常用的5个注解
(1)@Api:修饰整个类,描述Controller的作用
(2)@ApiOperation:描述一个类的一个方法,或者说一个接口
(3)@ApiParam:单个参数描述
@ApiModel::描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
@ApiProperty:描述一个model的属性。
其他注解:
- @ApiImplicitParams:用在方法上包含一组参数说明
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- paramType:参数放在哪个地方
- header-->请求参数的获取:@RequestHeader
- query-->请求参数的获取:@RequestParam
- path(用于restful接口)-->请求参数的获取:@PathVariable
- body(不常用)
- form(不常用)
- name:参数名
- dataType:参数类型
- required:参数是否必须传
- value:参数的意思
- defaultValue:参数的默认值
- paramType:参数放在哪个地方
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:数字,例如400
- message:信息,例如"请求参数没填好"
- response:抛出异常的类
更详细的可参考此网址:https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
许多注解多用用自然知道,熟能生巧。
原文地址:https://www.cnblogs.com/youcong/p/9011302.html