SpringBoot使用Swagger

大趋势下，目前很多的项目都采用了前后端分离的方式进行开发，最近我接触到的项目大多数都是采用了前后端分离的方式进行开发。既然摆脱了js和html的干扰，更优化的展示接口内容和调用是后端更多需要关注的事情。（非常重要的一点，如果你想简单上手直接使用文章中的项目框架模型，可以直接拉取项目代码：github：https://github.com/licunzhi/dream_on_sakura_rain/tree/master/springboot_swagger_demo）

 

这里介绍使用swagger作为接口文档展示的配置和使用，最终的效果将会是

​

 

 

首先，需要搭建基础的springboot项目。

这里推荐大家可以使用 springboot官方推荐模板快速生成工具，地址为：https://start.spring.io/

页面的效果是这样的

​

 

 

除了上面的方法支持创建简易的springboot项目的配置模板，实际上在开发工具中也有对这种方法的支持。

开发中使用idea也可以进行相关的操作，其中引用的地址可以是上面的地址，也可以是自己定义的，效果展示是下面的图片

 

 

 

​

 

 

 

 

你需要引入包文件

<!--swagger jar start--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency> <!--swagger jar end-->

 

 

启动类统计编写配置方法，效果图大概是这样的

​

 

 

 

 

配置代码

package com.example.springboot_swagger_demo; 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.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.example.springboot_swagger_demo.controller")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs") .description("相关描述") .termsOfServiceUrl("http:......").contact("sakura").version("1.0").build(); } } 

 

 

编写控制层的代码（这里面我已经吧经常会用到的注解都写上了，没有考虑到代码的规范性问题，只是为了给大家展示一下注解的含义相关用法）

package com.example.springboot_swagger_demo.controller; import com.example.springboot_swagger_demo.domain.Sakura; import com.example.springboot_swagger_demo.response.ResponseData; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.PutMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import springfox.documentation.annotations.ApiIgnore; import java.util.HashMap; import java.util.Map; import java.util.stream.Collectors; @RestController @RequestMapping("/sakura") @Api(value = "sakura基础数据接口", tags = "接口标识") //这里可以不设置，默认的展示效果是该类的名称SakuraController public class SakuraController { static Map<String, Sakura> sakuras = new HashMap<>(); @ApiOperation(value = "创建一个sakura", notes = "对接口的功能备注解释")//接口功能解释 @ApiImplicitParams( {// 多个参数的提示的展示方式，也可以单独只使用一个@ApiImplicitParam //@ApiImplicitParam(name = "id", value = "用户ID", dataType = "Long", paramType = "path"),//点进注解，会有paramType的其它选项和用法解释 @ApiImplicitParam(name = "sakura", value = "sakura实体类", required = true, dataType = "Sakura")//参数解释 }) @ApiResponses(value = {// 多个返回的提示的展示方式，也可以单独只使用一个@ApiImplicitParam @ApiResponse(code = 401, message = "未未授权"), @ApiResponse(code = 500, message = "server error"), @ApiResponse(code = 200, message = "success", response = ResponseData.class)}) @PostMapping public Object addRequest(@RequestBody Sakura sakura) { sakuras.put(sakura.getId(), sakura); return "success"; } @ApiOperation(value = "获取sakura信息", notes = "返回sakura所有信息") @GetMapping public Object getRequest() { return sakuras.entrySet().stream().map(entry -> entry.getValue()).collect(Collectors.toList()); } @ApiIgnore//注解标识不展示在swagger界面上 @PutMapping public String putRequest() { return "response put result message"; } } 

 

 

 

那么究竟有多少注解需要我们去探究，实际上没有多少，大概。。。。。就这么多吧

​

具体的含义和使用的详情要不然就是网上有了很多的解释，要不然就是点进注解之后英文解释的已经非常详细了，我这里面就不做解释了。

 

 

以上项目只是个人的简单总结和使用，不足之处大神勿喷。

 

 

欢迎访问交流群：589780530 
博主交流：2718272293
邮箱：[email protected]  [email protected]
github: https://github.com/licunzhi