Swagger(丝袜哥) 快速入门

共 6852字,需浏览 14分钟

 ·

2021-04-14 17:20

点击上方蓝色字体,选择“标星公众号”

优质文章,第一时间送达

76套java从入门到精通实战课程分享

swagger(丝袜哥)

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统,数以千计的开发人员,使用几乎所有的现代编程语言,都在支持和使用Swagger。使用Swagger生成API,我们可以得到交互式文档,自动生成代码的SDK以及API的发现特性等。


资源

官网

https://swagger.io/

在线编辑器

http://editor.swagger.io/

微服务整合Swagger,请看另一篇文章

Spring Cloud 整合Swagger 统一服务api


Swagger整合SpringBoot(单系统)

第三方(推荐)


https://github.com/SpringForAll/spring-boot-starter-swagger


依赖引入

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

在SpringBoot  启动类application 里面加入 @EnableSwagger2Doc  注解

加完注解后把项目启动起来,先看看效果 。访问路径默认都是localhost:端口号/swagger-ui.html


效果如图下:

他是会自动去扫描项目下的所有接口,这是项目里面自带的一些乱七八糟的,也不用去看这些。


我们可以在application.properties 文件中设置一些参数(这些都是最基本的,更多参数请参考官方文档)

#swagger标题
swagger.title=swagger titile
#swagger描述
swagger.description=swagger context
#swagger版本号
swagger.version=1.0.0

接下来,看运行效果,如图:

我们可以自己指定扫描路径,并为我们自己写的接口添加注释


创建一个接口类 MainController

@Api   //SwaggerApi注解 作用于接口类上
@ApiOperation   //SwaggerApi注解 作用于某个接口

@ApiParam //Swagger注解,作用于接口里面的参数

/**
 * @Auther: wan
 * @Date: 2021/4/7 16:41
 * @Description: com.wan.eurekaserver2.controller
 * @version: 1.0
 * @Api swaggerApi注解 对当前类描述
 */
@RestController
@RequestMapping("/main")
@Api(value = "用户管理",tags = {"用户管理"})
public class MainController {
 
    /**
     * @ApiOperation swaggerApi注解 对当前接口描述
     *     value:参数说明注解
     * @ApiParam  swagger注解说明
     *     name :参数名称
     *     required:是否必填
     *     example:写个示例
     *     value:参数说明注解
     * @param name
     * @return
     */
    @GetMapping(value="/getName")
    @ApiOperation(value = "获取wan列表")
    public String getList(@ApiParam(name="name",required = true,type = "String",example = "例如:小明",value = "姓名") String name,
    @ApiParam(name = "age",required = true,type = "integer",example = "20",value = "年龄") Integer age){
        return "user: name-"+name+",age-"+age;
    }
}

Swagger 会自动扫描项目下所有接口,会把一些不需要展示的接口显示出来,我们就可以指定Swagger的扫描路径


在application.properties 配置文件中

#指定分组名称
swagger.docket.maincontroller.title=main-controller
#指定当前分组扫描的路径-这个路径就是我创建的那个MainController的路径,你们自行修改
swagger.docket.maincontroller.base-package=com.wan.eurekaserver2.controller

运行,看效果,如下图:

点击这个接口里面看看有啥,效果如下图:

接下来,我们看看如果参数是Object 的时候,怎么在Swagger中配置参数说明


创建一个wanController ,把它和MainController 放在不同的文件夹下面,如下图:

/**
 * @Auther: wan
 * @Date: 2021/4/7 17:22
 * @Description: com.wan.eurekaserver2.wanController
 * @version: 1.0
 */
@RestController
@RequestMapping("/wan")
@Api(value = "wan管理1",tags = {"wan管理2"})  //@Api是接口类描述
public class wanController {
 
    @GetMapping("/getWanList")
    @ApiOperation(value = "获取wan列表")//@ApiOperation 是类中当前接口描述、@ApiParam是接口中参数描述
    public String getWanList(@ApiParam(value = "用户对象", example = "{json}") User user){
        return "getWanList:"+user.getName();
    }
 
    @PostMapping("/Delete")
    @ApiOperation(value = "删除Wan")
    public String gnList(@ApiParam(value = "id")Integer id){
        return "删除成功:"+id;
    }
 
}


在创建一个对象User,用来当请求参数,并加上注解


@ApiModel  // 就是用来修饰对象的


@ApiModelProperty  //修饰对象里面的属性的,value 可以配置属性说明,example 为参数示例

/**
 * @Auther: wan
 * @Date: 2021/4/8 10:34
 * @Description: com.wan.eurekaserver2.model  用户管理
 * @version: 1.0
 */
@ApiModel
public class User {
    @ApiModelProperty(value = "用户id",example = "1")
    private Integer id;
    @ApiModelProperty(value = "姓名",example = "小明")
    private String  name;
    @ApiModelProperty(value = "年龄",example = "18")
    private Integer age;
 
    public User(){
 
    }
 
    public Integer getId() {
        return id;
    }
 
    public void setId(Integer id) {
        this.id = id;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public Integer getAge() {
        return age;
    }
 
    public void setAge(Integer age) {
        this.age = age;
    }
 
}


然后我们可以在配置一个分组,


在application.properties 中加入如下配置:

swagger.docket.wancontroller.title=wan-controller
swagger.docket.wancontroller.base-package=com.wan.eurekaserver2.wanController

配置好了,运行。


效果如下图:

看看第二个分组里面的接口


在Swagger中 还自带postman 的功能,可以对接口进行发起请求,测试,操作如下图:

出现如下页面:

发起请求后返回的结果,如下图:

到此,Swagger 基本使用就是如此了。

————————————————

版权声明:本文为CSDN博主「风某人~Wind」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。

原文链接:

https://blog.csdn.net/qq_42087460/article/details/115512983





锋哥最新SpringCloud分布式电商秒杀课程发布

👇👇👇

👆长按上方微信二维码 2 秒





感谢点赞支持下哈 

浏览 41
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报