SpringBoot整合Swagger项目 demo SpringBoot

Swagger主要是用于前后端分离开发的时候，快速方便的输出API文档。
并且，为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。
优点

前后端分离开发
API文档非常明确
测试的时候不需要再使用URL输入浏览器的方式来访问Controller
传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
spring-boot与swagger的集成灰常简单

注解

@Api，是标注一个Controller（Class）为一个swagger资源（API）。
@ApiOperation,对一个操作或HTTP方法进行描述
@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：抛出异常的类

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
以上这些就是最常用的几个注解了。

其他注解详见：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
response code 各个代表什么
1xx（临时响应）
2xx （成功）
3xx （重定向）
4xx（请求错误）
5xx（服务器错误）
还有就是项目中自定义的返回码等
整合过程

pom.xml文件中引入swagger依赖：

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0

在SpringBoot启动类同目录下加上Swagger的config文件：

package com.martina.my_swagger; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author Martina * @create 2018年1/23 * @version 1.0 * * */@Configuration @EnableSwagger2 public class SwaggerConfig { //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定controller存放的目录路径 .apis(RequestHandlerSelectors.basePackage("com.martina.my_swagger.controller")) .paths(PathSelectors.any()) .build(); }private ApiInfo apiInfo() { return new ApiInfoBuilder() //标题 .title("swaggerDemo") .description("更多详情访问我的github：https://github.com/Martina001/").termsOfServiceUrl("https://github.com/Martina001/")//创建人 .contact(new Contact("Martina", "http://www.baidu.com", "")) .version("1.0") .build(); } }

在项目的controller中加上swagger的相关注解“：

/**\ * * @Api，是标注一个Controller（Class）为一个swagger资源（API）。 * @ApiOperation,对一个操作或HTTP方法进行描述 */ @Api("swagger测试") @RestController @RequestMapping(value="https://www.it610.com/") public class UserController { @Autowired private UserService userService; @ApiOperation(value="https://www.it610.com/article/方法测试",notes="根据传参返回对应的值") @RequestMapping(value="https://www.it610.com/test",method= RequestMethod.GET) public String word( @RequestParam("word") String word){ return word; }/** * 练手@RequestParam * @param userId * @return */ @ApiOperation(value="https://www.it610.com/article/方法测试",notes="根据传参返回对应的值") @RequestMapping(value="https://www.it610.com/getUser",method= RequestMethod.GET) public List getUser(@RequestParam("userId") int userId){ return userService.getUserById(userId); }/** * 练手@PathVariable * @param userId * @return */ @ApiOperation(value="https://www.it610.com/article/方法测试",notes="根据传参返回对应的值") @RequestMapping(value="https://www.it610.com/getUserById/{userId}",method= RequestMethod.GET) public List getUserById(@PathVariable("userId") int userId){ return userService.getUserById(userId); }@ApiOperation(value="https://www.it610.com/article/方法测试",notes="根据传参返回对应的值") @RequestMapping(value="https://www.it610.com/getAllUsers",method= RequestMethod.GET) public List getAllUsers(){ return userService.getAllUsers(); }@ApiOperation(value="https://www.it610.com/article/方法测试",notes="根据传参返回对应的值") @RequestMapping(value="https://www.it610.com/addUser",method= RequestMethod.POST) publicUser01addUser(User01 user01){ return userService.addUser(user01); } }

启动项目，在浏览器中输入 http://localhost:端口号/swagger-ui.html。

结果展示：

文章图片

文章图片

点击tryout：

文章图片

文章图片

错误记录
首先，mysql的连接，spring.datasource.driver-class-name=com.mysql.jdbc.Driver已经过时，使用新版的：

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

一直项目中显示红色，但是却不影响，原因未知：

文章图片

然后注意@Mapper，不要忘了

文章图片

虽然还是会显示红色，但是运行也没有影响，奇怪。

文章图片

文章图片

补充：

如果出现This application has no explicit mapping for /error, so you are seeing this as a fallback. 的异常，尝试在SwaggerConfig中，将该类继承自WebMvcConfigurationSupport，并且重写addResourceHandlers函数：

【SpringBoot整合Swagger项目 demo】

文章图片

文章图片

代码如下：

@EnableSwagger2 @Configuration public class SwaggerConfig extends WebMvcConfigurationSupport { //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定controller存放的目录路径 .apis(RequestHandlerSelectors.basePackage("com.martina.test01.controller")) .paths(PathSelectors.any()) .build(); }private ApiInfo apiInfo() { return new ApiInfoBuilder() //标题 .title("swaggerDemo") .description("更多详情访问我的github：https://github.com/Martina001/") // .termsOfServiceUrl("https://github.com/Martina001/")//创建人 .contact(new Contact("Martina", "http://www.baidu.com", "")) .version("1.0") .build(); } /** * 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式 * @param registry */ @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0); } }