springboot+mybatis-puls利用swagger构建api文档

项目开发常采用前后端分离的方式。前后端通过API进行交互，在Swagger UI中，前后端人员能够直观预览并且测试API，方便前后端人员同步开发。 在SpringBoot中集成swagger，步骤如下： 1.项目开始当然离不了的就是pom文件了，下面的依赖添加到Maven项目的pom.xml文件中。springfox-swagger2组件帮助我们自动生成描述API的json文件，而springfox-swagger-ui组件就是将这个json文件解析出来，用一种更友好的方式呈现出来。另外我这边操作数据库运用了mybatis-puls省去一部分的代码问题，有想了解mybatis-puls的可以去看我的上一篇文章https://www.cnblogs.com/WrBug/p/10177770.html

<name>springboot-mybatis-puls—swagger</name> <description>Demo project for Spring Boot</description> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.1.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.version> <mysql.version>5.1.24</mysql.version> <swagger2.version>2.7.0</swagger2.version> <plexus-build-api.version>0.0.7</plexus-build-api.version> <jackson-module-scala.version>2.9.1</jackson-module-scala.version> <commons-lang.version>3.1</commons-lang.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <!--swagger依赖包--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger2.version}</version> </dependency> <!----> <dependency> <groupId>org.freemarker</groupId> <artifactId>freemarker</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid</artifactId> <version>1.1.3</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatisplus-spring-boot-starter</artifactId> <version>1.0.5</version> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus</artifactId> <version>2.1.8</version> </dependency> <dependency> <groupId>org.apache.velocity</groupId> <artifactId>velocity-engine-core</artifactId> <version>2.0</version> </dependency> <!-- springboot整合mybatis--> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>1.3.1</version> </dependency> </dependencies> <!-- mybatis-puls 的插件代码生成器 --> <build> <finalName>mybatis_puls</finalName> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <plugin> <groupId>cn.pubinfo</groupId> <artifactId>mp-generator</artifactId> <version>1.01-SNAPSHOT</version> <configuration> <tables> <table>user</table><!--数据库表名--> </tables> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.5.1</version> <configuration> <source>1.8</source> <target>1.8</target> <skip>true</skip> </configuration> </plugin> </plugins> <resources> <resource> <directory>src/main/resources</directory> </resource> </resources> </build>

2.添加application.yml文件

server: port: 8080 servlet: context-path: /api spring: datasource: url: jdbc:mysql://localhost:3306/数据库名称?useUnicode=true&characterEncoding=utf8 username: **** password: ****** driver-class-name: com.mysql.jdbc.Driver mybatis-plus: mapper-locations: classpath:/mapper/*Mapper.xml type-aliases-package: cn.api.model

3.添加Swaager的配置类

package cn.api.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.context.request.async.DeferredResult; 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; /** * Swagger配置 * */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .genericModelSubstitutes(DeferredResult.class) .useDefaultResponseMessages(false) .forCodeGeneration(true) .apiInfo(apiInfo()) .pathMapping("/")// base，最终调用接口后会和paths拼接在一起 .select() .apis(RequestHandlerSelectors.basePackage("cn.api.controller")) //这块是关键哦，最后你的接口能不能显示出来都在这呢 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger构建api文档") .description("简单优雅的restful风格") .termsOfServiceUrl("https://github.com/springfox/springfox-demos") .version("1.0") .build(); } } 或者 @Configuration @EnableSwagger2 public class SwaggerConfig { 　　@Resource 　　private TypeResolver typeResolver @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .pathMapping("/") .select() .apis(RequestHandlerSelectors.basePackage("cn.*.controller")) .paths(PathSelectors.any()) .build().apiInfo(new ApiInfoBuilder() .title("swagger接口") .description("swagger接口...") .version("1.0") .build()); 　　　　　　　　　　.additionalModels(typeResolver.resolve(OperateLog.class)); //解决没用到的实体类显示 } }

4.在需要暴露的API上添加需要在Swagger UI页面上当然要显示应用相关的介绍信息，生成API就是为了就是方便前后端人员同步开发。举个例子吧~ 在Controller类上添加@API注解，说明该类的作用；该类下包含增删改查几个方法，给大家一个全面的示范，至于service、dao层的实现，留给大家自己发挥吧~主要是在方法上添加@ApiOperation，@ApiImplicitParam注解，作用是对方法以及参数的说明

package cn.api.controller; import cn.api.service.UserService; import com.baomidou.mybatisplus.mapper.EntityWrapper; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import cn.api.model.User; import javax.annotation.Resource; import java.util.List; /** * @author kuancz */ @Api(tags = "用户表") @RestController @RequestMapping("/user") public class UserController { @Resource private UserService userService; /** * 所有用户信息 * */ @GetMapping("/queryAll") @ApiOperation(value = "获取集合", notes = "获取所有实体") public List<User> queryUser() { List<User> userList = userService.selectList(new EntityWrapper<>()); return userList; } @GetMapping("/test") @ApiOperation(value = "获取", notes = "测试用户") @ApiImplicitParam(name = "name",value = "名字",required = true,dataType = "String",paramType = "query") public List<User> getEmployee(@RequestParam String name) { return userService.selectList(new EntityWrapper<User>().eq("name",name)); } /** * 用户新增 * * @param user 实体 */ @PostMapping("/insert") @ApiOperation(value = "增加", notes = "根据实体增加用户") public Integer insert(@RequestBody User user) { userService.insert(user); return user.getId(); } @ApiOperation(value = "修改用户", notes = "根据实体更新用户") @PatchMapping("/update") public boolean update(@RequestBody User user) { boolean update = userService.update(user,new EntityWrapper<>()); return update; } @ApiOperation(value = "删除用户",notes = "根据id删除对应实体") @DeleteMapping("/delete") @ApiImplicitParam(name = "id",value = "id",required = true,dataType = "Integer",paramType = "query") public boolean delete(@RequestParam Integer id) { boolean del = userService.deleteById(id); return del; } @ApiOperation(value = "查询",notes = "根据ID获取用户") @GetMapping("/getByid") @ApiImplicitParam(name = "id",value = "id",required = true,dataType = "Integer",paramType = "query") public User getByid(@RequestParam Integer id) { User user = userService.selectById(id); return user; } }

5.启动SpringBoot项目，访问http:http://localhost:8080/api/swagger-ui.html#/页面，注意了，我这里是因为在application.properties配置了项目路径server.servlet.context-path=/api，所以才在上面的url加上/api，一般若无特殊的配置，直接访问http://localhost:8080/swagger-ui.html即可