一、swagger简介

1、前后端分离的特点

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

2、在没有swagger之前

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

3、swagger的作用

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

4、 swagger的优点

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

二、集成swagger

1、新建springboot项目

我就用了上期项目进行演示：微信程序开发之小程序交互_爱嘤斯塔的博客-CSDN博客

2、集成swagger

①、打开https://mvnrepository.com/search?q=springfox&__cf_chl_f_tk=zlPqPT9H1JT8hcQO6TabU.rJEvDSdQvb6OLZemvXjH4-1646986778-0-gaNycGzNBlE https://mvnrepository.com/https://mvnrepository.com/search?q=springfox&__cf_chl_f_tk=zlPqPT9H1JT8hcQO6TabU.rJEvDSdQvb6OLZemvXjH4-1646986778-0-gaNycGzNBlE，查找springbox，在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>

②、编写swagger的配置类

注意：该配置类需要根据自己的项目修改，如以下配置
        paths 指定需要生成文档的url规则
        title 文档标题
        description 描述

package com.lv.code.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()
//         请求处理选择器,扫描controller层
        .apis(RequestHandlerSelectors.basePackage("com.lv.code.controller"))
//            上面包内的所有请求
        .paths(PathSelectors.any())
        .build();
    }

//api简介
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        .title("l蹦跶v")
        .description("SwaggerDemo API DOC")
        .version("1.0")
        .termsOfServiceUrl("https://www.bd.com")
        .build();
    }
}

启动进入：

在controller层方法内指定提交方法：

    @RequestMapping("/login",method= RequestMethod.POST)
    public ResponseResult<?> login(@RequestBody User user){
        return userService.findUserByAccount(user);
    }

可以尝试连接：

填完数据连接：

访问成功：

3、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" 表示参数放在哪里

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

defaultValue=" 参数的默认值 "

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

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

swagger-annotations 1.3.10 API

例如：

package com.lv.code.controller;

import com.lv.code.pojo.User;
import com.lv.code.service.IuserService;
import com.lv.code.util.response.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Async;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Api(tags = "用户操作类")
public class UserController {

    @Autowired
    private IuserService userService;

    @ApiOperation(value = "登录方法")
    @ApiImplicitParam(value="user",required = true,name = "用户信息",paramType = "body")
    @RequestMapping(value="/login",method= RequestMethod.POST)
    public ResponseResult<?> login(@RequestBody User user){
        return userService.findUserByAccount(user);
    }

}

实体类：

package com.lv.code.pojo;

import java.io.Serializable;
import java.util.Date;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;
import org.springframework.format.annotation.DateTimeFormat;

import javax.persistence.*;

/**
 * t_user
 * @author 
 */
@Data
@Table(name = "t_user")
@AllArgsConstructor
@NoArgsConstructor
@Accessors(chain = true)
@ApiModel(description = "用户实体类")
public class User implements Serializable {

//    组件自增
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty(name = "id",value = "用户id",example = "0")
    private Long id;

    @ApiModelProperty(name = "account",value = "用户账号",example = "")
    private String account;

    @ApiModelProperty(name = "password",value = "用户密码",example = "")
    private String password;

//    将前端发送的string数据转换为date类型，输出date类型
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
//    将date类型转换为string类型,接收date类型
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(name = "modifyTime",value = "用户修改时间",example = "2022-03-04 13:14:00")
    private Date modifyTime;

//   将前端发送的string数据转换为date类型，输出date类型
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
//   将date类型转换为string类型,接收date类型
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(name = "createTime",value = "用户登录时间",example = "2022-03-04 13:14:00")
    private Date createTime;

    private static final long serialVersionUID = 1L;
}

备注成功：

前言技术之swagger

一、swagger简介

1、前后端分离的特点

2、在没有swagger之前

3、swagger的作用

4、 swagger的优点

二、集成swagger

1、新建springboot项目

2、集成swagger

②、编写swagger的配置类

3、swagger常用注解

例如：

本期内容结束~~~~~~~~~~~~~~~~~

猜你喜欢

前言技术之swagger

一、swagger简介

1、前后端分离的特点

2、 在没有swagger之前

3、swagger的作用

4、 swagger的优点

二、集成swagger

1、新建springboot项目

2、集成swagger

②、编写swagger的配置类

3、swagger常用注解

例如：

本期内容结束~~~~~~~~~~~~~~~~~

猜你喜欢

2、在没有swagger之前