swagger

一、前后端分离的特点

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

二、在没有swagger之前

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

三、swagger的作用

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

四、swagger的优点

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

五、集成swagger

1、新建springboot项目

2、集成swagger

1.pom.xml

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>

2.编写swagger配置类

package com.xnx.swagger2.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();
    }
}

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

修改后

3、开发一个controller用于测试

修改后：

package com.xnx.swagger2.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;

/**
 * @author xnx
 * @create 2023-01-07 15:11
 */
@Api(tags = "swagger入门案例")
@RestController
@RequestMapping("/swagger")
public class HelloController {
    @ApiOperation("打招呼的接口")
    @GetMapping("/hello")
    public Map hello(){
        Map map = new HashMap();
        map.put("dode",200);
        map.put("msg","操作成功!!!");
        return map;
    }
}

4、启动服务，验证集成效果

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

说明集成成功

六、swagger常用注解

七、swagger使用综合案例

package com.xnx.swagger2.controller;

import com.xnx.swagger2.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;
    }
}

package com.xnx.swagger2.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;

}

八、会议OA之swagger

1.pom.xml

<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.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.6.2version>
        <relativePath/> 
    parent>
    <groupId>com.zking.ssmgroupId>
    <artifactId>ssm-oaartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <description>OAPROdescription>
    <properties>
        <java.version>1.8java.version>
        <fastjson.version>1.2.70fastjson.version>
        <jackson.version>2.9.8jackson.version>
    properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-jdbcartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-thymeleafartifactId>
        dependency>
        <dependency>
            <groupId>org.mybatis.spring.bootgroupId>
            <artifactId>mybatis-spring-boot-starterartifactId>
            <version>2.2.1version>
        dependency>

        <dependency>
            <groupId>mysqlgroupId>
            <artifactId>mysql-connector-javaartifactId>
            <version>5.1.44version>
            <scope>runtimescope>
        dependency>
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
            <optional>trueoptional>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>

        <dependency>
            <groupId>com.alibabagroupId>
            <artifactId>fastjsonartifactId>
            <version>${fastjson.version}version>
        dependency>


        <dependency>
            <groupId>com.github.binarywanggroupId>
            <artifactId>weixin-java-miniappartifactId>
            <version>3.3.0version>
        dependency>

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>
    dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombokgroupId>
                            <artifactId>lombokartifactId>
                        exclude>
                    excludes>
                configuration>
            plugin>

            <plugin>
                <groupId>org.mybatis.generatorgroupId>
                <artifactId>mybatis-generator-maven-pluginartifactId>
                <version>1.3.2version>
                <dependencies>
                    
                    <dependency>
                        <groupId>mysqlgroupId>
                        <artifactId>mysql-connector-javaartifactId>
                        <version>${mysql.version}version>
                    dependency>
                dependencies>
                <configuration>
                    <overwrite>trueoverwrite>
                configuration>
            plugin>
        plugins>
    build>

project>

2.swagger的整合配置类

package com.zking.ssm.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();
    }
}

注意：此时SpringBoot (2.7.7) 版本与swagger2 (2.9.2) 的版本不兼容，需要添加application.yml相关配置
3.application.yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4.web层接口服务提供

package com.zking.ssm.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.zking.ssm.wxcontroller;

import com.zking.ssm.mapper.InfoMapper;
import com.zking.ssm.model.Info;
import com.zking.ssm.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.*;

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(@RequestBody Info info) {
        List<Info> infoList = infoMapper.list(info);
        Map<Object, Object> data = new HashMap<Object, Object>();
        data.put("infoList",infoList);
        return ResponseUtil.ok(data);
    }
}

package com.zking.ssm.model;

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

import java.util.Date;

@ApiModel("会议信息实体")
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;
    }
}

5.测试结果