当前位置：首页 > news >正文

1 swagger简单案例

news 2025/8/27 11:17:59

1.1 加入依赖

<!--swagger图形化接口--><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><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.8.7</version>
</dependency>

1.2 在config包中写swagger配置类SwaggerConfig

swagger配置类的代码如下：（直接套用，但部分需要修改）

package com.ieslab.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;
import java.util.ArrayList;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket docket(Environment environment){// 设置要现实的swagger环境Profiles profiles = Profiles.of("dev","test");// 获取项目的环境,如果项目环境在profiles中则返回trueboolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())  //配置 Swagger ApiInfo 基本信息.groupName("jiangzeyu").enable(flag)  //配置是否启动swagger.select()//RequestHandlerSelector配置要扫描接口的方式//basePackage：指定要扫描的包.apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))/** paths()：只扫描哪些类* any()代表扫描全部* none()代表都不扫描* withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口* withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口* ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口*/.paths(PathSelectors.any()).build();  //工厂模式}@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);}//配置 Swagger信息=apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("zhangsan","无","333@qq.com");return new ApiInfo("Swagger API 文档",                    //文档标题"这个是一个 Swagger 接口文档。",              //文档描述"v1.0",                                       //文档版本"没有网站",                   //队伍的网站地址contact,                                              //作者信息"Apache 2.0",                                  //许可证"http://www.apache.org/licenses/LICENSE-2.0",//许可证Urlnew ArrayList());}}

剖析：

在类上要加入两个注解：@Configuration和@EnableSwagger2；

然后开始写docket方法，返回Docket对象，入参是Environment environment，用来后续对application的环境进行判断，控制swagger是否启动：

// 设置要现实的swagger环境,dev代表application-dev.yaml
Profiles profiles = Profiles.of("dev","test");
// 获取项目的环境,如果项目环境在profiles中则返回true
boolean flag = environment.acceptsProfiles(profiles);

接着，返回配置的Docket对象：

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())  // 配置 Swagger ApiInfo 基本信息,因此要创建apiInfo方法.groupName("jiangzeyu")   .enable(flag)  //配置是否启动swagger.select()//RequestHandlerSelector配置要扫描接口的方式//basePackage：指定要扫描的包.apis(RequestHandlerSelectors.basePackage("com.ieslab.demo.controller"))/** paths()：只扫描哪些类,()里的参数有any()、none()、ant(“需要扫描的请求”)、withClassAnnotation、withMethodAnnotation,后面两个不常用，请自行百度* any()代表扫描全部* none()代表都不扫描* withClassAnnotation:扫描类上有某个注解的接口，比如说RestController就是扫描类上有@RestController的类生成接口* withMethodAnnotation:扫描方法上有某个注解的接口，比如说GetMapping就是扫描方法上有@GetMapping的类生成接口* ant(“/hello/*”)：扫描包含/hello/**请求的类生成接口*/.paths(PathSelectors.any()).build();  //工厂模式}

其中，apiInfo传入apiInfo方法返回的ApiInfo对象（需要自己写apiInfo方法），enable传入的参数可由项目的环境决定，apis(RequestHandlerSelectors.basePackage())传入的是需要扫描的包路径，paths()传入的是在包路径下扫描哪些类，groupName() 传入的是测试接口归属哪个人，如下图所示：

多个docket方法就可以代表不同人的测试接口：（注意方法名不要相同！）

    @Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);}

效果：

apiInfo()方法如下：套模板即可。

    //配置 Swagger信息=apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("zhangsan","无","333@qq.com");return new ApiInfo("Swagger API 文档",                    //文档标题"这个是一个 Swagger 接口文档。",              //文档描述"v1.0",                                       //文档版本"没有网站",                   //队伍的网站地址contact,                                              //作者信息"Apache 2.0",                                  //许可证"http://www.apache.org/licenses/LICENSE-2.0",//许可证Urlnew ArrayList());}

1.3 创建实体类User

package com.ieslab.demo.emtity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("这是User的实体类") // 给实体类加文档注释
public class User {@ApiModelProperty("主键id")private Integer userId;@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;}

剖析：只要实体类在Controller被使用，而控制类又被swagger扫描到，就会被展示出来，实体类的注解都是给文档加注释用的。

1.4 创建UserDao接口和UserDaoImpl实现类

UserDao：

package com.ieslab.demo.dao;import com.ieslab.demo.emtity.User;public interface UserDao {// 添加用户User addUser(Integer userId,String userName,String password);}

UserDaoImpl：因为前端传来的是一个JSON对象，会使用@RequestBody将其封装为User对象，然后从这个User对象中拿各个属性。

package com.ieslab.demo.dao.impl;import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import org.springframework.stereotype.Repository;import java.util.HashMap;
import java.util.Map;@Repository
public class UserDaoImpl implements UserDao {private static Map<Integer,User> userMap = null;static {userMap = new HashMap<Integer, User>();userMap.put(100,new User(100,"zhangsan","777"));userMap.put(102,new User(102,"lisi","888"));userMap.put(103,new User(103,"wangwu","999"));userMap.put(104,new User(104,"zhaoliu","000"));}@Overridepublic User addUser(Integer userId,String userName,String password) {User user = new User(userId,userName,password);userMap.put(user.getUserId(),user);return user;}}

1.5 创建Controller对象，接收请求

package com.ieslab.demo.controller;
import com.ieslab.demo.dao.UserDao;
import com.ieslab.demo.emtity.User;
import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Slf4j
@RestController
public class MyController {@Autowired // 相当于使用new UserDaoimpl()private UserDao userDao;@PostMapping(value = "/addUser")@ApiOperation(value = "AddUser接口",httpMethod = "POST",notes = "这是AddUser接口的详细说明") // 给方法加注释public User addUser(@RequestBody @ApiParam("用户") User userInput){  // 加入@RequestBody Spring自动将传过来的JSON类型的数据和我们的类匹配，说明输入是JSON格式的数据User user = userDao.addUser(userInput.getUserId(), userInput.getUsername(), userInput.getPassword());return user;}}

剖析：

重点在于Post方法不能接收基本类型的数据，需要把它们用JSON格式进行封装，然后@RequestBody会把JSON格式的数据转为对应的实体类。

注意！类上的是@RestController而不是@Controller，因为@Controller后类中的方法return的要转发的页面，而不会被以指定的格式写入Http response body中。

其他大部分注解都是加注释用的：