Springboot整合Swagger、Swagger详解及Swagger常用注解

最新推荐文章于 2024-05-03 11:47:20 发布

置顶 Wait for you�

最新推荐文章于 2024-05-03 11:47:20 发布

阅读量390

点赞数 1

文章标签： spring spring boot restful java

本文链接：https://blog.csdn.net/weixin_43865977/article/details/109097834

版权

Springboot整合Swagger、Swagger详解及Swagger常用注解

Swagger是什么？它能干什么？

Swagger是什么？它能干什么？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测

Swagger的优势

1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
2.提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

快速搭建springboot项目

1.访问：https://start.spring.io/
2. 根据页面提示，选择构建工具，开发语言，项目信息等。
3. 在这里插入图片描述
4.点击 Generate the project，生成项目模板，生成之后会将压缩包下载到本地
5.解压使用IDE导入项目

添加Swagger Maven依赖

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

编写Swagger配置类

package com.project.becurrent.common.config.swagger;

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;

/**
 * @Description:SwaggerConfig
 * @Author: wk
 * @CreateDate: 2020/10/15 13:50
 * @Version: 1.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

	/**
     *  通过createRestApi函数创建Docket的Bean之后，
     *  * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
     *  * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     *  * apis()函数扫描所有Controller中定义的API， 并产生文档内容（除了被@ApiIgnore指定的请求）
     * @return
     * @date        2020/10/15 16:24
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(aipInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.project.becurrent"))//包名换成自己的
                .paths(PathSelectors.any()).build();
    }
	 /**
     * 创建该Api的基本信息（这些基本信息会展现在文档页面中）
     * @return
     */
    private ApiInfo aipInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("be-current Swagger API接口").description("be-current Swagger API接口文档")
                .build();
    }
}

集成 Swagger 管理 API 文档

controller中的使用

package com.project.becurrent.system.controller;

import com.alibaba.fastjson.JSON;
import com.project.becurrent.common.util.Result;
import com.project.becurrent.common.util.encrypt.MD5Util;
import com.project.becurrent.system.domain.UserDO;
import com.project.becurrent.system.service.UserService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.thymeleaf.ThymeleafProperties;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;

/**
 * @Author: wk
 * @CreateDate: 2020/10/12 9:33
 * @Version: 1.0
 */
@Controller
@Api(value = "LoginController", tags = {"登录接口"})
public class LoginController {

    @Autowired
    private UserService userService;

    @GetMapping("/login")
    @ApiOperation("登录页面跳转")
    public String login() {
        return "login";
    }

    @PostMapping("/submit")
    @ResponseBody
    @ApiOperation("登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "username", dataType = "String", required = true),
            @ApiImplicitParam(name = "password", value = "password", dataType = "String", required = true),
            @ApiImplicitParam(name = "verifyCode", value = "verifyCode", dataType = "String", required = true),
    })
    public Result login(@RequestParam("username") String username, @RequestParam("password") String password, @RequestParam("verifyCode") String verifyCode) {
        UserDO userDO = userService.getByUsername(username);
        if (userDO == null) return Result.error("账号错误，请重新输入！");
        if (!MD5Util.encrypt(username, password).equals(userDO.getPassword())) {
            return Result.error("账号或密码错误，请重试！");
        }
        return Result.success();
    }

    @ApiOperation("test")
    @PostMapping("/test")
    public Result test(@ApiParam(value = "参数说明",name = "参数名",required = true) String test){
        return null;
    }

}

domain中的使用

package com.project.becurrent.system.domain;

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

import java.io.Serializable;

@Data
@ApiModel(value = "",description = "描述")
public class UserDO implements Serializable {
    private static final long serialVersionUID = 1L;
    //
    @ApiModelProperty(value = "用户id",name = "userId",required = true,example = "举例")
    private Long userId;
    // 用户名
    @ApiModelProperty(value = "用户名d",name = "username",required = true,example = "举例")
    private String username;
   
}

编写好后启动项目并访问 ip+:”端口号/swagger-ui.html 例如：127.0.0.1:8888/swagger-ui.html
在这里插入图片描述
当看到此页面说明Swagger整合成功

Swagger常用注解说明

1：@Api()用于类，表示标识这个类是swagger的资源，一般用于Controller类上；
2：@ApiOperation()用于方法，表示一个http请求的操作，对接口方法进行一个说明；
3：@ApiParam()用于方法参数说明，表示对参数的添加元数据（说明或是否必填等）；
4：@ApiModel()用于类，表示对类进行说明，一般用于参数用实体类接收；
5：@ApiModelProperty()用于实体类字段上，表示对字段进行说明，可以配合@ApiModel()使用；
6：@ApiIgnore()用于类、方法、方法参数上，表示这个类、方法、方法参数被忽略；不生成该类、该方法、该方法参数的文档；
7：@ApiImplicitParam() 用于方法，表示单独的请求参数；
8：@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam()；
9：@ApiResponses()注解在方法上表响应，一般与@ApiResponse公用

@Api()

@Api()用于类；表示标识这个类是swagger的资源
tags——表示说明
value——也是说明，可以使用tags替代，但是tags如果有多个值，会生成多个list
例：@Api(value = “LoginController”, tags = {“登录接口”})
效果图如下：
在这里插入图片描述

@ApiOperation()

用于方法；表示一个http请求的操作
value——用于方法的描述
notes——用于提示内容
tags——用于重新分组视情况而用）
例： @ApiOperation(“test”)
效果图如下：
在这里插入图片描述

@ApiParam()

用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name——参数名
value——参数说明
required——是否必填
例：@ApiParam(value = “test”,name = “test”,required = true)
效果图如下：
在这里插入图片描述

@ApiModel()

用于类；表示对类进行说明，用于参数用实体类接收
value——表示对象名（可省略）
description——描述（可省略）

@ApiModelProperty()

value——字段说明
name——重写属性名字
dataType——重写属性类型
required——是否必填
example——举例说明
hidden——隐藏

@ApiIgnore()

用于类或者方法上，可以不被swagger显示在页面上

@ApiImplicitParam()

用于方法表示单独的请求参数
name——参数明
value——参数说明
dataType——数据类型
paramType——参数类型
example——举例说明
例：@ApiImplicitParam(name=“name”,value=“用户名”,dataType=“String”, paramType = “query”)

@ApiImplicitParams()

用于方法，包含多个 @ApiImplicitParam
例：
@ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query"),@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query"),@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") })

Wait for you�

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
1
评论
Springboot整合Swagger、Swagger详解及Swagger常用注解

Springboot整合Swagger、Swagger详解及Swagger常用注解Swagger是什么？它能干什么？Swagger的优势快速搭建springboot项目添加Swagger Maven依赖编写Swagger配置类集成 Swagger 管理 API 文档Swagger常用注解说明@Api()@ApiOperation()@ApiParam()@ApiModel()@ApiModelProperty()@ApiIgnore()@ApiImplicitParam()@ApiImplicitParam
复制链接

扫一扫