springmvc集成swagger
pom.xml
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.3</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.3</version>
</dependency>
<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>
spring-mvc.xml
<!-- swagger静态文件路径
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
-->
配置开启注解创建bean对象
package com.eternal.admin.util;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.eternal"))//包
.paths(PathSelectors.any())//paths如果在生产情况下可以调整为PathSelectors.none(),即不显示所有接口信息;
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("永恒项目 RESTful APIs")
.description("永恒项目api接口文档")
.version("1.0")
.build();
}
}
springboot集成swagger
pom.xml
<!--springfox依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
添加静态资源配置
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {/**
* 配置静态资源路径以及上传文件的路径
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("/upload/**").addResourceLocations(environment.getProperty("spring.resources.static-locations"));
/*swagger-ui*/
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
配置类
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("net.laoyeye.yyblog.web.frontend"))
.paths(PathSelectors.none())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("yyblog项目 RESTful APIs")
.description("yyblog项目api接口文档")
.version("1.0")
.build();
}
}
controller
/**
* 前台文章Controller
* @author 小卖铺的老爷爷
* @date 2018年5月5日
* @website www.laoyeye.net
*/
@Api(description="文章查询")
@Controller
@RequestMapping("/article")
public class ArticleController {
@Autowired
private ArticleService articleService;
@Autowired
private SettingService settingService;
@Autowired
private CateService cateService;
@Autowired
private TagReferService tagReferService;
@Autowired
private UserService userService;
@Autowired
private ArticleMapper articleMapper;
@Autowired
private CommentService commentService;
@ApiOperation(value="文章查询接口")
@ApiImplicitParam(name = "id", value = "文章ID", required = true, dataType = "Long")
@GetMapping("/{id}")
public String index(Model model, @PathVariable("id") Long id) {
try {
articleService.updateViewsById(id);
} catch (Exception ignore) {
}
List<Setting> settings = settingService.listAll();
Map<String,Object> map = new HashMap<String,Object>();
for (Setting setting : settings) {
map.put(setting.getCode(), setting.getValue());
}
Article article = articleService.getArticleById(id);
model.addAttribute("settings", map);
model.addAttribute("cateList", cateService.listAllCate());
model.addAttribute("article", article);
model.addAttribute("tags", tagReferService.listNameByArticleId(article.getId()));
model.addAttribute("author", userService.getNicknameById(article.getAuthorId()));
//回头改
model.addAttribute("articles", articleMapper.listArticleByTitle(null));
model.addAttribute("similars", articleMapper.listArticleByTitle(null));
CommentQuery query = new CommentQuery();
query.setLimit(10);
query.setPage(1);
query.setArticleId(id);
model.addAttribute("comments", commentService.listCommentByArticleId(query));
return "frontend/article";
}
@ApiOperation(value="文章评论查询接口")
@PostMapping("/comments")
@ResponseBody
public DataGridResult comments(CommentQuery query) {
//设置默认10
query.setLimit(10);
return commentService.listCommentByArticleId(query);
}
@ApiOperation(value="文章点赞接口")
@ApiImplicitParam(name = "articleId", value = "文章ID", required = true, dataType = "Long")
@PostMapping("/approve")
@ResponseBody
public YYBlogResult approve(@RequestParam Long articleId) {
return articleService.updateApproveCntById(articleId);
}
}
常用的一些注解
@Api:用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query -->请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiParam:单个参数描述
@ApiModel:描述一个Model的信息,用对象来接收参数(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
最后,好像忘记说swagger文档的路径了
如果你的项目在根目录:http://localhost:8080/swagger-ui.html
如果不是根目录那就是:http://localhost:8080/你的项目名/swagger-ui.html
页面出现 fetching resource list: http://localhost:8080/eternal/v2/api-docs; Please wait.
可能是使用其他json方式如fastjson 如果使用jackjson是没问题的
注解使用
开始的时候,在controller层使用@RequestParam的时候,发现这个参数是必须要输入值的,但是我们有时候必须查询的时候允许参数为空,使用这个注解就不行了。
在集成了swagger2后,找了半天的原因,发现使用@ApiImplicitParam这个注解可以解决这个问题。
对应下面的参数。
所以我们可以使用这个注解来解决我们所遇到的参考为空的问题。
而且已经集成了swagger2,所以我们尽量来使用这个注解吧。
说明:
1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4)
2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成)
没有集成的请参见
SpringBoot集成springfox-swagger2构建restful API
SpringMVC集成springfox-swagger2构建restful API
官网WIKI
常用注解:
- @Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作
- @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
- @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
- @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
具体使用举例说明:
@Api()
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
}
效果图:
@ApiOperation() 用于方法;表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用)
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
// userService可忽略,是业务逻辑
User user = userService.getUserInfo();
return user;
}
}
效果图:
@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用户名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id数组",hidden=true)
private String[] ids;
private List<String> idList;
//省略get/set
}
@ApiOperation("更改用户信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
int num = userService.updateUserInfo(user);
return num;
}
效果图:
@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上
比较简单, 这里不做举例
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明
@ApiOperation("查询测试")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(){
}
效果图: