swagger

最新推荐文章于 2024-07-09 22:57:10 发布
最新推荐文章于 2024-07-09 22:57:10 发布
阅读量854 收藏 3
点赞数
文章标签： spring boot spring java Powered by 金山文档
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_64313980/article/details/128587497
版权

1.前后端分离的特点

前后端分离是的前端与后端之间的职责更加明确
后台： 负责业务处理
前端： 负责显示逻辑
在这种情况下，前端和后端可以分别交付给专业的开发人员去做，所以是必须要定义前后端直接的对接
接口，否则各自为是则项目无法集成，这时就需要一个文档来定义统一的接口。

2.在没有swagger之前

在没有swagger之间，我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即：
在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了
作用，甚至会起到反作用。

3.swagger的作用

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是
在开发接口时可以通过swagger将接口文档定义好，同时也方便以后的维护。

4.swagger的优点

号称时最流行的API框架
接口文档在线生成，避免同步的麻烦
可以支持在线对接口执行测试
支持多语言

5.集成swagger

5.1 新建springboot项目

使用集成开发工具创建一个springboot工程

5.2 集成swagger

1.pom.xml

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.编写swagger配置类

package com.ljj.swagger2test.config;
​
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
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 SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.ant("/**")) //项目名
                .build();
​
    }
​
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerDemoAPIDOC")
                .description("SwaggerDemoAPIDOC")
                .version("1.0")
                .termsOfServiceUrl("https://www.baidu.com").build();
    }
}

报错：

这是在加载一个插件 但是2我使用的2.77的版本已经没有这个插件了 所以我将版本换成了稍微老一点的2.5.11就好了

注意：SpringBoot与swagger2的版本对应关系，否则项目是启动不成功的，这里的版本对应关系如下

springboot 2.6以前可以用 swagger2.x
springboot 2.7.7 与swagger2.x会有冲突 项目无法启动
springboot 2.6以上整合swagger3待发掘

5.3 启动服务，验证集成效果

服务启动后，访问：http://localhost:8080/swagger-ui.html

5.4 开发一个controller用于测试

其中使用到的注解@Api，@ApiOperation 在下文中有解释说明

package com.ljj.swagger2test.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

//@Api(tags = {"这是swagger入门类","作用2"})
@Api(tags = "这是swagger入门类")
@RestController
@RequestMapping("/swagger")
public class HelloController {
//    @ApiOperation(value = "", tags = "swagger入门方法")
    @ApiOperation(value = "swagger入门方法")
@GetMapping("/hello")
public Map<String,Object> hello(){
        Map<String,Object> map = new HashMap<>();
        map.put("code",200);
        map.put("msg","响应成功！！！");
return map;
    }
}

查看集成效果

6.swagger常用注解

注解

位置

作用

参数

@Api

类

标识这个类是swagger的资源

tags：说明该类的作用，参数是个数组，可 以填多个。

value="该参数没什么意义，在UI界面上不显示，所以不用配置"

description = "用户基本信息操作"

@ApiOperation

方法

表示一个http请求的操作

value="方法的用途和作用"

notes="方法的注意事项和备注"

tags：说明该方法的作用，参数是个数组，可以填多 个。

格式：tags={"作用1","作用2"}

@ApiParam

方法，参数

对参数使用说明（如：说明 或是否必填等）

value="用户名" 描述参数的意义

name="name" 参数的变量名

required=true 参数是否必选

@ApiModel

类

表示对类进行说明，用于参 数用实体类接收，一般用在 DTO上

description="描述实体的作用"

@ApiModelProperty

方法，字段

表示对model属性的说明

value="用户名" 描述参 数的意义

name="name" 参数的变量名

required=true 参数是否必选

@ApiIgnore

类，方法，参数

表示这个方法或者类被忽略

无

@ApiImplicitParams

方法

包含多@ApiImplicitParam

@ApiImplicitParam

方法

表示单独的请求参数

name="参数名称"

value="参数说明"

dataType="数据类型"

paramType="query" 表示参数放在哪里

defaultValue="参数的默认值"

required="true" 表示参数是否必须传

paramType="query"的解释如下

header 请求参数的获取：@RequestHeader
query 请求参数的获取：@RequestParam
path（用于restful接口） 请求参数的获取：@PathVariable
body（不常用）
form（不常用）

更全面的信息可以参考官方说明文档：

https://docs.swagger.io/swagger-core/apidocs/index.html

7.swagger使用综合案例

package com.ljj.swagger2test.controller;

import com.ljj.swagger2test.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/swagger/api")
@Api(tags = "swagger所有注解的讲解")
public class SwaggerController {


    @ApiOperation(value = "欢迎信息")
    @GetMapping("/hello")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名称", dataType = "string", paramType = "query", required = true),
            @ApiImplicitParam(name = "msg", value="消息", dataType = "string", paramType = "query", required = true)
    })
    public Object hello(String name, String msg) {
        Map<String, Object> map = new HashMap<>();
        map.put("code", 200);
        map.put("msg", "操作成功");
        map.put("info",name+":"+msg);
        return map;
    }

    @PostMapping("/register")
    @ApiOperation("注册用户接口")
    @ApiResponses({
            @ApiResponse(code = 5001001,message = "错误1"),
            @ApiResponse(code = 5001002,message = "错误2"),
            @ApiResponse(code = 5001003,message = "错误3")
    })
    public Object register(User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("code", 5001002);
        map.put("msg", "操作成功");
        map.put("info",user);
        return map;
    }

    @PutMapping("/edit")
    @ApiOperation("修改用户信息")
    public Object edit(@RequestBody User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("code", 200);
        map.put("msg", "操作成功");
        map.put("info",user);
        return map;
    }

    @DeleteMapping("/delete/{id}")
    @ApiOperation("删除用户")
    @ApiImplicitParam(name = "id", value="用户ID", dataType = "string", paramType = "path", required = true)
    public Object delete(@PathVariable("id") String id) {
        Map<String, Object> map = new HashMap<>();
        map.put("code", 200);
        map.put("msg", "操作成功");
        map.put("info",id);
        return map;
    }
}

User实体类

package com.ljj.swagger2test.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description = "用户信息")
public class User {

    @ApiModelProperty(value = "用户名", name="name", required = true)
    private String name;

    @ApiModelProperty(value = "密码", name="passwd", required = true)
    private String passwd;

}

pom依赖

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

注册用户接口演示

欢迎信息演示

修改用户信息演示

传入json数据 @RequestBody

删除用户演示

路径传参 paramType = "path"

8.会议oa之swagger

打开我们的oa项目后台

  1. pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.2</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.ljj</groupId>
    <artifactId>minoa</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>minoa</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
        <fastjson.version>1.2.70</fastjson.version>
        <jackson.version>2.9.8</jackson.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.2.1</version>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>5.1.44</version>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>${fastjson.version}</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.mybatis.generator</groupId>
                <artifactId>mybatis-generator-maven-plugin</artifactId>
                <version>1.3.2</version>
                <dependencies>
                    <!--使用Mybatis-generator插件不能使用太高版本的mysql驱动 -->
                    <dependency>
                        <groupId>mysql</groupId>
                        <artifactId>mysql-connector-java</artifactId>
                        <version>${mysql.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <overwrite>true</overwrite>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

  1. swagger的整合配置类

package com.ljj.minoa.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
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 swaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.ant("/**")) //项目名
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerDemoAPIDOC")
                .description("SwaggerDemoAPIDOC")
                .version("1.0")
                .termsOfServiceUrl("https://www.baidu.com").build();
    }
}

3.application.yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4.controller层接口服务提供

package com.ljj.minoa.wxcontroller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Autho donkee
 * @Since 2022/1/20
 */
@Api(tags = "这是一个测试的接口列表")
@RestController
public class HelloController {
    @ApiOperation("这是一个测试的具体接口")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

package com.ljj.minoa.wxcontroller;

import com.ljj.minoa.mapper.InfoMapper;
import com.ljj.minoa.model.Info;
import com.ljj.minoa.util.ResponseUtil;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @Autho donkee
 * @Since 2022/6/29
 */
@Api(tags = "会议oa小程序的接口列表")
@RestController
@RequestMapping("/wx/home")
public class WxHomeController {
    @Autowired
    private InfoMapper infoMapper;
    @ApiOperation("会议查询接口（历史会议，待开会议，所有会议。。。）")
    @GetMapping("/index")
    public Object index(Info info) {
        List<Info> infoList = infoMapper.list(info);
        Map<Object, Object> data = new HashMap<Object, Object>();
        data.put("infoList",infoList);
        return ResponseUtil.ok(data);
    }
}

5.Info实体类

package com.ljj.minoa.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.util.Date;

@ApiModel(description = "会议信息")
public class Info {
    @ApiModelProperty(value = "会议ID", name="id", required = false)
    private Long id;

    @ApiModelProperty(value = "会议标题", name="title", required = false)
    private String title;

    @ApiModelProperty(value = "会议内容", name="content", required = false)
    private String content;

    @ApiModelProperty(value = "参与者", name="canyuze", required = false)
    private String canyuze;

    @ApiModelProperty(value = "列席人员", name="liexize", required = false)
    private String liexize;

    @ApiModelProperty(value = "主持人", name="zhuchiren", required = false)
    private String zhuchiren;

    @ApiModelProperty(value = "会议地点", name="location", required = false)
    private String location;

    @ApiModelProperty(value = "会议开始时间", name="starttime", required = false)
    private Date starttime;

    @ApiModelProperty(value = "会议结束时间", name="endtime", required = false)
    private Date endtime;

    @ApiModelProperty(value = "附件", name="fujian", required = false)
    private String fujian;

    @ApiModelProperty(value = "会议状态", name="state", required = false)
    private Integer state;

    @ApiModelProperty(value = "审批人", name="auditperson", required = false)
    private String auditperson;

    @ApiModelProperty(value = "审批时间", name="audittime", required = false)
    private Date audittime;

    @ApiModelProperty(value = "会议座位图片", name="seatpic", required = false)
    private String seatpic;

    @ApiModelProperty(value = "备注", name="remark", required = false)
    private String remark;

    public Info(Long id, String title, String content, String canyuze, String liexize, String zhuchiren, String location, Date starttime, Date endtime, String fujian, Integer state, String auditperson, Date audittime, String seatpic, String remark) {
        this.id = id;
        this.title = title;
        this.content = content;
        this.canyuze = canyuze;
        this.liexize = liexize;
        this.zhuchiren = zhuchiren;
        this.location = location;
        this.starttime = starttime;
        this.endtime = endtime;
        this.fujian = fujian;
        this.state = state;
        this.auditperson = auditperson;
        this.audittime = audittime;
        this.seatpic = seatpic;
        this.remark = remark;
    }

    public Info() {
        super();
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }

    public String getCanyuze() {
        return canyuze;
    }

    public void setCanyuze(String canyuze) {
        this.canyuze = canyuze;
    }

    public String getLiexize() {
        return liexize;
    }

    public void setLiexize(String liexize) {
        this.liexize = liexize;
    }

    public String getZhuchiren() {
        return zhuchiren;
    }

    public void setZhuchiren(String zhuchiren) {
        this.zhuchiren = zhuchiren;
    }

    public String getLocation() {
        return location;
    }

    public void setLocation(String location) {
        this.location = location;
    }

    public Date getStarttime() {
        return starttime;
    }

    public void setStarttime(Date starttime) {
        this.starttime = starttime;
    }

    public Date getEndtime() {
        return endtime;
    }

    public void setEndtime(Date endtime) {
        this.endtime = endtime;
    }

    public String getFujian() {
        return fujian;
    }

    public void setFujian(String fujian) {
        this.fujian = fujian;
    }

    public Integer getState() {
        return state;
    }

    public void setState(Integer state) {
        this.state = state;
    }

    public String getAuditperson() {
        return auditperson;
    }

    public void setAuditperson(String auditperson) {
        this.auditperson = auditperson;
    }

    public Date getAudittime() {
        return audittime;
    }

    public void setAudittime(Date audittime) {
        this.audittime = audittime;
    }

    public String getSeatpic() {
        return seatpic;
    }

    public void setSeatpic(String seatpic) {
        this.seatpic = seatpic;
    }

    public String getRemark() {
        return remark;
    }

    public void setRemark(String remark) {
        this.remark = remark;
    }
}

6.测试结果

非必填 可直接执行该指令

数据结果

如何输入json数据？

添加@RequestBody 即可

按提示输入json字符串

本期内容到此结束 咱们下期见！！！

小刘学编程.
关注
  • 0
    点赞
  • 踩
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Swagger
一个孤独漫步者的遐想的博客
08-13 505
Swagger一、pom.xml二、创建配置类 SwaggerConfig三、添加注释，生成doc四、swagger-ui四、doc五、配置权限（升级）方法一方法二 一、pom.xml <springfox-swagger.version>2.8.0</springfox-swagger.version> <swagger-bootstrap-ui.version>1.7.2</swagger-bootstrap-ui.version> <!-- ht
swagger开启身份认证
04-08
### swagger开启身份认证 在现代Web开发中，API文档自动生成工具如Swagger变得越来越重要，它们不仅能够提高开发效率，还能够帮助团队更好地管理和维护API接口。然而，随着API暴露给外部用户，安全问题也日益突出。...
Swagger简介
热门推荐
Ghost Stories
03-22 26万+
欢迎访问本人博客：http://wangnan.tech   欢迎关注简书：    点击打开链接   欢迎关注微信公众号： 前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视...
Swagger | 十分钟开启swagger大师生涯
最新发布
赵同学的博客
07-09 1119
前后端分离前端 -> 前端控制层、视图层后端 -> 后端控制层、服务层、数据访问层前后端通过API进行交互前后端相对独立且松耦合产生的问题前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发解决方案首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险Swagger号称世界上最流行的API框架Restful Api 文档在线自动生成器 =>API 文档 与API 定义同步更新直接运行，在线测试API。
07SpringBoot集成Swagger
niannujiao6的博客
12-28 174
Swagger简介： 前后端分离问题的出现造就了Swagger的出现，问题就是：前后端的集成，前端或者后端无法做到及时协商，尽早解决，最终会导致问题集中的爆发。Swagger的出现实时跟踪了最新的API,降低集成风险。 优点 号称世界上最流行的API框架 Restful API文档自动生成器==>API文档与API定义同步更新 直接运行，在线测试API 支持多种语言，如：JAVA PHP等 官网：https://swagger.io/ SpringBoot集成Swagger 要求：jdk1.8+否
swagger本地程序
06-06
Swagger是一个强大的API开发工具，主要用于设计、构建、记录和使用RESTful web服务。在这个“swagger本地程序”中，我们关注的是Swagger Editor，这是一个用于编写OpenAPI规范（以前称为Swagger规格）的在线工具，...
Swagger,NET4.5版本的
06-24
Swagger是一个流行的API开发工具，主要用于设计、构建、文档化和使用RESTful web服务。在.NET框架中，Swagger可以通过Swashbuckle库实现，这个库为ASP.NET Web API提供了集成Swagger的功能。在这个.NET 4.5版本的...
Swagger使用指南
02-24
本文来自于csdn，本文主要介绍了swagger配置类里面,要配置自己的controller包路径以及如何使用swagger，希望对您的学习有所帮助。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务...
swagger.zip
04-30
Swagger 是一个广泛使用的开源框架，主要用于构建RESTful API的文档化和测试。它提供了一种标准的方式来描述Web服务接口，使得开发者可以轻松地理解和使用这些接口。Swagger通过JSON格式的OpenAPI规范来定义API，这...
使用Swagger编写API文档指南
"swagger官方文档" Swagger 是一个广泛使用的API框架，它的主要目的是为了帮助开发者创建、设计、文档化和测试API。Swagger 提供了一种标准化的方法，使得API的描述和实现之间保持一致，促进了不同团队之间的协作。...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值