Swagger接口文档 —— 手把手教学，全方位超详细小白能看懂，百分百能用Java版_业界新闻

发布时间:2024-08-07 16:59

阅读量:0

🧸欢迎来到dream_ready的博客，📜相信您对博主首页也很感兴趣o (ˉ▽ˉ；)
博主首页，更多redis、java等优质好文以及各种保姆级教程等您挖掘！

一、介绍

二、导入依赖

三、在配置类中加入 knife4j 相关配置

八、设置全局都穿的参数 —— 例如token

一、介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。

官网：https://swagger.io/

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

二、导入依赖

<dependency>     <groupId>com.github.xiaoymin</groupId>     <artifactId>knife4j-spring-boot-starter</artifactId>     <version>3.0.2</version> </dependency>

此处导入的是Knife4j，这是一个为MVC框架集成Swagger生成文档的解决方案

三、在配置类中加入 knife4j 相关配置

亲爱的朋友，希望你不要告诉我你不会写配置类，不会配置类的话看文末，最下面有最基础的配置类的教程，保证你能用上最好用的Swagger文档

是在配置类中添加下面内容哦

注意修改里面的一些内容，比如汉字部分以及那个扫描包的路径

    /**      * 通过knife4j生成接口文档      * @return      */     @Bean     public Docket docket1() {         log.info("准备生成接口文档...");         ApiInfo apiInfo = new ApiInfoBuilder()                 .title("皮肤肿瘤分类项目接口文档")                 .version("2.0")                 .description("皮肤肿瘤分类项目接口文档")                 .build();         Docket docket = new Docket(DocumentationType.SWAGGER_2)                 .groupName("接口")                 .apiInfo(apiInfo)                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.example.cvresume.controller"))                 .paths(PathSelectors.any())                 .build();         return docket;     }

这个扫描包的路径切记要修改哦

需要注意的是，这个方法可以设置多个，来使接口文档分页，只要方法名不重复即可

四、设置静态资源映射

设置静态资源映射，否则接口文档页面无法访问

也是在配置类中书写哦

下面这个基本是固定的，不用改，若你想玩一下Swagger的更多玩法，那么你可以去查阅官方文档

    /**      * 设置静态资源映射      * @param registry      */     protected void addResourceHandlers(ResourceHandlerRegistry registry) {         log.info("开始设置静态资源映射...");         registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");         registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");     }

五、注意放开拦截器拦截

要注意拦截器拦截，比如如果你设置的有JWT校验，那么就要在配置拦截器那里放开下面这几个静态资源

"/swagger-resources/**", "/doc.html", "/webjars/**", "/v2/**", "/swagger-ui.html/**"

类似我这样写：

六、使用方式

其实你已经可以使用了，来进入这个页面看一下吧

当你在写配置的时候，需要指定一个扫描路径，它就会自动扫描所有接口，获取对应的数据，构建接口文档

浏览器输入下面这个地址

注意修改ip和端口号为你正在使用的，其他不变

http://127.0.0.1:8080/doc.html

只不过你会发现它没有备注，当你遇到很麻烦的数据的时候，根本不知道每个属性是干嘛的，这时候就需要使用注解了

利用注解标记Controller和Model层对应的数据，然后利用这些标记的数据自动生成接口文档中对应数据的备注

常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

标记数据

现在我对我的login接口进行改造，使其出现在接口文档上

我这里将原来和标记后的代码都进行了展示，主要是看注解，不要看我的逻辑代码，此篇博客只是为了让大家真正上手Swagger的使用

Controller

原来的：

标记后：

可以看到我用@Api标记了UserCroller这个类，用@ApiOperation标记了login这个方法

Model

其实基本项目中的所有Model都要做标记，因为不一定啥时候用到，Model做标记的主要原因是让Swagger知道传来了什么参数(传对象时)，或返回了什么参数

原来的：

@Data public class User {     private Integer id;     private String username; // 用户名     private String password; // 密码     private String nickname; // 昵称     private String avatarPath; // 头像路径     private String sex; // 性别     private String phone; // 电话     private Integer role; // 角色     private String hospital; // 医院名称     private LocalDateTime createTime;     private LocalDateTime updateTime; }

标记后：

可以看到，我利用了@ApiModel标记实体类，用@ApiModelProperty标记属性

@Data @ApiModel(description = "用户信息") public class User {      @ApiModelProperty(value = "用户ID")     private Integer id;      @ApiModelProperty(value = "用户名")     private String username;      @ApiModelProperty(value = "密码")     private String password;      @ApiModelProperty(value = "昵称")     private String nickname;      @ApiModelProperty(value = "头像路径")     private String avatarPath;      @ApiModelProperty(value = "性别")     private String sex;      @ApiModelProperty(value = "电话")     private String phone;      @ApiModelProperty(value = "角色")     private Integer role;      @ApiModelProperty(value = "医院名称")     private String hospital;      @ApiModelProperty(value = "创建时间")     private LocalDateTime createTime;      @ApiModelProperty(value = "更新时间")     private LocalDateTime updateTime; }

然后因为我这个项目有一个统一返回的对象Result，所以我对Result也要用注解加个标记

原来的：