php整合Spring技巧_SpringBoot整合Swagger2在线文档

文章目录 [+]

Swagger的工具很多，但SpringBoot中整合Swagger紧张是利用Swagger来构建强大的Restful文档。
也便是里面的Swagger UI工具。

这里我们用的版本是Swagger2。

php整合Spring技巧_SpringBoot整合Swagger2在线文档

1.创建Springboot项目

选择web、 lombok、 mysql、spring data jpa 依赖（也可以将spring data jpa 换成mybatis干系依赖）

（图片来自网络侵删）

项目创建成功后在pom文件中添加druid依赖包

完成后pom文件如下：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId>  <version>5.1.45</version> <scope>runtime</scope> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot-starter</artifactId> <version>1.1.10</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency></dependencies>

添加数据库配置信息：

# 数据库的基本配置spring.datasource.driver-class-name=com.mysql.jdbc.Driverspring.datasource.username=rootspring.datasource.password=rootspring.datasource.url=jdbc:mysql://localhost:3306/boot1?characterEncoding=utf8&serverTimezone=GMT%2B8#配置连接池spring.datasource.type=com.alibaba.druid.pool.DruidDataSource# JPA配置spring.jpa.database=mysql# 是否在掌握台打印SQLspring.jpa.show-sql=truespring.jpa.hibernate.ddl-auto=update# 指定默认的存储引擎为InnoDB，默认情形下，自动创建表的时候会利用 MyISAM 做表的引擎，# 如果配置了数据库方言为 MySQL57Dialect，则利用 InnoDB 做表的引擎。 spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect2.创建Restful风格的Api

构造图如下：

User类：

package com.example.swagger.pojo;import io.swagger.annotations.ApiModel;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;import javax.persistence.;@Data@NoArgsConstructor@AllArgsConstructor@Entity@Table(name = "users")public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private int id; private String uname; private int age;}

UserRepository类：

package com.example.swagger.dao;import com.example.swagger.pojo.User;import org.springframework.data.jpa.repository.JpaRepository;public interface UserRepository extends JpaRepository<User,Integer> {}

这里省略了service层，直接在掌握层里调用dao层

userController类：

package com.example.swagger.controller;import com.example.swagger.dao.UserRepository;import com.example.swagger.pojo.User;import com.example.swagger.util.Response;import com.example.swagger.util.ResponseResult;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;import java.util.List;@RestControllerpublic class UserController { @Autowired private UserRepository userRepository; //查询所有 @GetMapping("/users") public ResponseResult<List<User>> selectUsers() { List<User> usersList= userRepository.findAll(); return Response.createOkResp(usersList); } //根据id查询 @GetMapping("/users/{id}") public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id) { User user= userRepository.findById(id).get(); return Response.createOkResp(user); } //添加 @PostMapping("/users") public ResponseResult addUser(User user) { userRepository.save(user); return Response.createOkResp("add success"); }}3.添加Swagger23.1添加干系jar包

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version></dependency>3.2 开启Swagger

swagger2 在springboot框架中利用须要开启 @EnableSwagger2，同时它支持自定义ui页面的一些信息

3.3 查看在线文档页

设置上面两个步骤后，打开 http://localhost:8080/swagger-ui.html

就可以看到接口信息

3.4 配置 Docket（可选）

我们把一个Docket类的一个实例添加到Spring的 BeanFactory中，以实现Swagger页面一些展示信息的定制化，例如作者，标题，描述等信息，也可以进行一些相应的配置项，例如扫描的Controller类根本包名等等。
swagger会在初始化时从Spring的 BeanFactory中获取该实例(如果没有则利用默认的Docket实例)，来完成初始化。

package com.example.swagger.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;@Configurationpublic class Swagger2 { @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo( new ApiInfoBuilder() .contact(new Contact("daimenglaoshi", "", "2398779723@qq.com")) .title("SpringBoot整合Swagger2") .build() ); }}

上面是对Docket进行一个非常大略的配置。
效果如图

3.5 给Api接口添加表明

package com.example.swagger.controller;import com.example.swagger.dao.UserRepository;import com.example.swagger.pojo.User;import com.example.swagger.util.Response;import com.example.swagger.util.ResponseResult;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;import java.util.List;@RestController@Api(tags = "用户管理干系接口")public class UserController { @Autowired private UserRepository userRepository; //查询所有 @GetMapping("/users") @ApiOperation("查询所有用户的接口") public ResponseResult<List<User>> selectUsers() { List<User> usersList= userRepository.findAll(); return Response.createOkResp(usersList); } //根据id查询 @GetMapping("/users/{id}") @ApiOperation("根据id查询用户的接口") @ApiImplicitParam(name = "id", value = "用户id", required = true) public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id) { User user= userRepository.findById(id).get(); return Response.createOkResp(user); } //添加 @PostMapping("/users") @ApiOperation("添加用户") public ResponseResult addUser(User user) { userRepository.save(user); return Response.createOkResp("add success"); }}

这里边利用到了多个表明：@Api表明：用来标记当前 Controller 的功能。 @ApiOperation表明：用来标记一个方法的浸染。 @ApiImplicitParam表明：用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。如果有多个参数，则须要利用多个 @ApiImplicitParam 表明来描述，多个 @ApiImplicitParam 表明须要放在一个 @ApiImplicitParams 表明中。须要把稳的是，@ApiImplicitParam 表明中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限定就没用了，以是如果开拓者须要指定一个参数必填， @RequestParam(required = true) 表明还是不能省略。3.6 参数是工具时

如果参数是一个工具（例如上文的添加接口），对付参数的描述也可以放在实体类中。

package com.example.swagger.pojo;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;import javax.persistence.;@Data@NoArgsConstructor@AllArgsConstructor@Entity@Table(name = "users")@ApiModel(description = "用户字段")public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) @ApiModelProperty(value = "用户id", name = "id", example = "1") private int id; @ApiModelProperty(value = "用户名", name = "uname", required = true, example = "daimenglaoshi") private String uname; @ApiModelProperty(value = "年事", name = "age", example = "18") private int age;}3.7 查看接口文档

http://localhost:8080/swagger-ui.html