1 swagger简单案例

paipai大星2023-08-07 23:47

1.1 加入依赖

java 复制代码 
<!--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配置类的代码如下：（直接套用，但部分需要修改）

java 复制代码 
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 {
    @Bean
    public Docket docket(Environment environment){
        // 设置要现实的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        // 获取项目的环境,如果项目环境在profiles中则返回true
        boolean 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();  //工厂模式
    }

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
    }

    //配置 Swagger信息=apiInfo
    private 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",//许可证Url
                new ArrayList());
    }



}

剖析：

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

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

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

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

java 复制代码 
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方法就可以代表不同人的测试接口：（注意方法名不要相同！）

java 复制代码 
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A").enable(true);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B").enable(true);
    }

效果：

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

java 复制代码 
    //配置 Swagger信息=apiInfo
    private 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",//许可证Url
                new ArrayList());
    }

1.3 创建实体类User

java 复制代码 
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：

java 复制代码 
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对象中拿各个属性。

java 复制代码 
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"));
    }

    @Override
    public 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对象，接收请求

java 复制代码 
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中。

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

1.6 使用swagger进行测试

访问：http://localhost:8080/swagger-ui.html

然后选择自己的组，点击控制类：

点击要测试的接口（方法）：

点击try it out开始测试：

编辑要传入的JSON数据，编辑后执行：

测试成功：

相关推荐
time never ceases13 分钟前
使用docker方式进行Oracle数据库的物理迁移(helowin/oracle_11g)
数据库·docker·oracle
Frank牛蛙17 分钟前
1.每日SQL----2024/11/7
数据库·sql
Ciderw19 分钟前
块存储、文件存储和对象存储详细介绍
网络·数据库·nvme·对象存储·存储·块存储·文件存储
薛晓刚19 分钟前
数据库优化指南：如何将基本功能运用到极致？
数据库
小白冲鸭22 分钟前
【报错解决】使用@SpringJunitConfig时报空指针异常
spring·java后端开发
stars_User23 分钟前
MySQL数据库面试题（下）
数据库·mysql
沈询-阿里33 分钟前
java-智能识别车牌号_基于spring ai和开源国产大模型_qwen vl
java·开发语言
AaVictory.39 分钟前
Android 开发 Java中 list实现 按照时间格式 yyyy-MM-dd HH:mm 顺序
android·java·list
未来之窗软件服务1 小时前
sql速度优化多条合并为一条语句
数据库
山东布谷科技官方1 小时前
布谷直播源码部署服务器关于数据库配置的详细说明
运维·服务器·数据库·直播系统源码·直播源码·直播系统搭建·直播软件开发
热门推荐
01【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总02(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04【AIGC】重塑未来的科技巨轮05全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）06【经验分享】Ubuntu22.04安装微信(linux官方版)07基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测08Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO09RAG 实践- Ollama+RagFlow 部署本地知识库10【TC3xx芯片】TC3xx芯片电源管理系统PMS详解