SpringBoot+Swagger详细使用方法

一、接口文档概述

swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具,在前后端开发之前,后端要先出接口文档,前端根据接口文档来进行项目的开发,双方开发结束后在进行联调测试。

二、常用注解

java 复制代码
- @Api()用于类;(controller) 
表示标识这个类是swagger的资源
- @ApiOperation()用于方法; 
表示一个http请求的操作 
- @ApiParam()用于方法,参数,字段说明; 
表示对参数的添加元数据(说明或是否必填等) 
- @ApiModel()用于类 主要是用于接受对象的信息
表示对类进行说明,用于参数用实体类接收 
- @ApiModelProperty()用于方法,字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类,方法,方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
-@ApiResponse() 用于方法
对返回响应头的说明
-@ApiResponses用于方法,包含多个@ApiResponse

三 、pom依赖

1、在pom.xml文件中添加swagger相关依赖

html 复制代码
		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。

java 复制代码
package com.aaa.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


@Configuration
@EnableSwagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.aaa.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs")
                .description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台")
                .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin") //代码的路径
                .contact("小宇")
                .version("1.0")
                .build();
    }


}

springboot版本比较高的时候可能会和swagger出现版本不兼容的问题想要解决这个问题可以在

application文件中加上:

html 复制代码
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

四、在controller中的使用

主要用于在API上做一些声明

java 复制代码
package com.aniu.test1.controller;


import com.aniu.test1.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;


@Api(tags = "用户管理")
@RestController
public class UserController {


    @ApiOperation("添加用户")
    @PostMapping("/add")
    public User add(@ApiParam("用户") User user){
        return new User();
    }


    @ApiOperation("修改用户")
    @PostMapping("/update")
    public String update() {
        return "修改";
    }


    @ApiOperation("删除用户")
    @GetMapping("/delete")
    public boolean delete(@ApiParam("用户编号") Integer id) {
        return true;
    }


    @ApiOperation("查询用户")
    @GetMapping("/query")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002,message = "缺少参数") })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "电影名", dataType = "String", paramType = "query", required = true),})
    public User query(@RequestParam String name) {
        User user = new User();
        user.setUserName("name");
        user.setPassword("password");
        return  user;
    }
}

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

五、使用bootstrap的ui

现已更名knife4j

https://doc.xiaominfo.com/docs/action/springboot

html 复制代码
<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.7.0</version>
  </dependency>
  
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

输入http://localhost:项目端口号/doc.html

相关推荐
ahauedu2 分钟前
Apache POI 依赖版本冲突导致 NoSuchFieldError: Factory 报错
java·maven·apache
tang_jian_dong2 分钟前
springboot + vue3 拉取海康视频点位及播放
spring boot·后端·音视频
黄团团13 分钟前
SpringBoot连接Sftp服务器实现文件上传/下载(亲测可用)
服务器·spring boot·github
运维帮手大橙子25 分钟前
字符串缓冲区和正则表达式
java·开发语言
程序员爱钓鱼31 分钟前
Go语言实战案例-括号匹配算法
后端·google·go
程序员爱钓鱼36 分钟前
Go语言实战案例-判断字符串是否由另一个字符串的字母组成
后端·google·go
丶小鱼丶1 小时前
栈算法之【有效括号】
java·算法
郝学胜-神的一滴2 小时前
SpringBoot实战指南:从快速入门到生产级部署(2025最新版)
java·spring boot·后端·程序人生
鼠鼠我捏,要死了捏5 小时前
Java 虚拟线程在高并发微服务中的实战经验分享
java·microservices·virtualthreads
武子康6 小时前
Java-82 深入浅出 MySQL 内部架构:服务层、存储引擎与文件系统全覆盖
java·开发语言·数据库·学习·mysql·spring·微服务