Swagger2详细教程

痛定思痛。 2024-03-31 10:04 59阅读 0赞

**目录**

前言：

添加依赖：

启用Swagger2：

快速启动：

访问地址：

Swagger配置类：

注解：

注解@Api：

注解@ApiOperation：

注解@ApiIgnore：

注解@ApiModel：

注解@ApiModelProperty：

注解@ApiImplicitParams：

自定义注解：

自定义实体：

Controller示例：

--------------------

## 前言： ##

现在很多开发都是前后端分离，前后端分离的时代接口文档反倒成了个讨人嫌的工作，书写接口文档是一件费时费力的活，而 Swagger 可以根据程序代码自动生成在线接口文档，这篇文章主要展示如何在springboot项目中集成[swagger][]\-ui。确实swagger诞生至今已经很久了，但是这不影响踩到swagger的误区。我个人在使用的过程中遇到一个问题，下面给大家分享下我的解决方法吧。

## 添加依赖： ##

<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>

## 启用Swagger2： ##

我们添加完依赖后，但是boot应用不认得swagger，所以我们要在启动类上添加上对应的注解，从而开启Swagger2.

import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * EnableSwagger2 是springfox提供的一个注解，代表swagger2相关技术开启。
     * 会扫描当前类所在包，及子包所有类型中的注解
     */
    @SpringBootApplication
    @EnableSwagger2
    public class App {
        public static void main(String[] args) {
            SpringApplication.run(App.class,args);
        }
    }

## 快速启动： ##

@RestController
    public class MyController {
    
        @PostMapping("/post")
        public String post(){
            return "post";
        }
    
        @GetMapping("/get")
        public String get(){
            return "get";
        }
    }

## 访问地址： ##

默认地址为：hhtp://127.0.0.1:8080/swagger-ui.html

下图为访问效果：

![a364d6cc6fe708e746bf8c15ff9adace.png][]

可能很多多人会说，这个和别人的swagger文档怎么不太一样。当然不太一样了，这只是swagger的快速简单入门，想要不一样的swagger，快和我一起进行下去。

## Swagger配置类： ##

import com.google.common.base.Predicates;
    import com.xiaoguai.anno.MyAnno4Swagger;
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import static com.google.common.base.Predicates.not;
    import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;
    
    @Configuration
    public class SwaggerConfiguration {
        /**
         * 创建Docket类型的对象，并使用Spring容器管理
         * Docket是Swagger的全局配置对象
         *
         * @return
         */
        @Bean
        public Docket getDocket() {
            //标明为swagger
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
    
            //API帮助文档的描述信息
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .contact(   //配置swagger文档主体内容
                            new Contact(
                                    "王小怪Swagger开发文档",   //是文档发布者名称
                                    "www.baidu.com",            //是文档发布者的网站地址
                                    "909634056@qq.com")         //是文档发布者的电子邮箱
                    )
                    .title("Swagger框架学习帮助文档")
                    .description("Swagger框架学习帮助文档，详细描述-Swagger框架是一个用于开发RestAPI帮助文档")
                    .version("1.1")
                    .build();
    
            //给docket上下文配置api描述信息
            docket.apiInfo(apiInfo);
    
            docket
                    .select()   //获取Docket中的选择器 返回ApiSelectorBuilder构建选择器。如：扫描什么包的注解
                    .apis(
                            Predicates.not(     //取反
                                    RequestHandlerSelectors.withMethodAnnotation(   //当方法有注解的时候返回true
                                            MyAnno4Swagger.class)   //方法上有什么注解时返回true
                            )
                    )
                    .apis(RequestHandlerSelectors.basePackage("com.xiaoguai.controller"))   //设定扫描的基础包(包含子包)
    
                    .paths(
                            Predicates.or(  //多规则匹配 有一符合即可显示
                                    PathSelectors.regex("/swagger/.*"),  //使用正则表达式，约束生成API文档的路径地址
                                    PathSelectors.regex("/swagger2/.*")     //多路径进行匹配
                            )
                    )
                    .build();
            return docket;
        };
    }

配置完配置类，我们再去进行访问以下试试。现在是不是有那么些神似了。

![666138127a95ee041dc14bb3e84654ab.png][]

## 注解： ##

当然，学习swagger也十分有必要学习一下里面 的注解。

package com.xiaoguai.controller;
    
    import com.xiaoguai.anno.MyAnno4Swagger;
    import com.xiaoguai.entity.MyEntity;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    import springfox.documentation.annotations.ApiIgnore;
    
    /**
     * @Api -描述当前类型生成帮助文档的信息
     *  属性  -
     *      -tags ： 给当前类型定义别名，可以多个。定义几个别名就在ui视图显示几个访问器访问菜单。
     */
    @RestController
    @RequestMapping("/swagger")
    @Api(tags = {"MyController","SwaggerController"},description = "测试API类型的描述信息")  //tags可以理解为起别名
    public class MyController {
    
        @RequestMapping("/getMyEntity")
        public MyEntity getMyEntity(){
            return new MyEntity();
        }
    
        @GetMapping("/test")
        //@ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "query",dataType = "String")
        @ApiImplicitParams(value = {
                @ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "query",dataType = "String"),
                @ApiImplicitParam(name = "n",value = "n参数描述",required = true,paramType = "query",dataType = "Integer")
        })
        public String test(String m,int n){
            return "test";
        }
    
        @ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用处理-处理POST请求的方法")
        @PostMapping("/post")
        public String post(
                @ApiParam(name = "用户名",value = "用户新增时提供的用户名",required = true) String a,
                @ApiParam(name = "密码",value = "用户新增时提供的密码",required = false)String b){
            return "post";
        }
    
        @ApiIgnore  //忽略，当前注解描述的额方法或类型，不生成api帮助文档
        @GetMapping("/get")
        public String get(){
            return "get";
        }
    
        @MyAnno4Swagger
        @RequestMapping("/req")
        public String req(String m){
            return "req";
        }
    }

### 注解@Api： ###

@Api：描述当前类型生成帮助文档的信息
        tags：给当前类型定义别名，可以多个。定义几个别名就在ui视图显示几个访问器访问菜单。
        description：为描述信息。

### 注解@ApiOperation： ###

@ApiOperation：用于方法，表示一个http请求的操作
        value：说明方法的作用
    	notes：方法的备注说明

### 注解@ApiIgnore： ###

@ApiIgnore：忽略，当前注解描述的额方法或类型，不生成api帮助文档

### 注解@ApiModel： ###

@ApiModel：用于类表示对类进行说明，用于参数用实体类接收

### 注解@ApiModelProperty： ###

@ApiModelProperty：用于每个属性上面，说明属性的含义。
        value：属性值
        name：属性名
        required：是否必须
        example：举例
        hidden：是否隐藏

### 注解@ApiImplicitParams： ###

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面
    	name：参数名
    	value：参数的汉字说明、解释
    	required：参数是否必须传，默认false
    	paramType：参数放在哪个地方，查询参数类型，这里有几种形式：
    	header --> 请求参数的获取：@RequestHeader，参数在 request headers 里边提交
    	query --> 请求参数的获取：@RequestParam，直接跟参数，完成自动映射赋值
    	path（用于 restful 接口）--> 请求参数的获取：@PathVariable，以地址的形式提交数据
    	body（不常用）--> 以流的形式提交 仅支持 POST
    	form（不常用）--> 以 form 表单的形式提交 仅支持 POST
    	dataType：参数类型，默认String，其它值 dataType="Integer"
    	defaultValue：参数的默认值

## 自定义注解： ##

import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    
    /**
     * @Target -描述当前的注解可以定义在什么资源上
     *  属性 value
     *      -定义具体的资源。 包括：
     *          -ElementType.METHOD 可以定义在方法上
     *          -ElementType.TYPE 可以定义在类上
     *          -ElementType.FIELD 可以定义在属性上
     *          -ElementType.PARAMETER 可以定义在参数上
     * @Retention -当前注解什么时候有效
     *  属性 value
     *      -定义具体的生效标记
     *          -RetentionPolicy.RUNTIME  -运行时有效
     *          -RetentionPolicy.SOURCE   -源码中有效
     *          -RetentionPolicy.CLASDS   -字节码有效
     */
    @Target(value={ElementType.TYPE,ElementType.METHOD})
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyAnno4Swagger {
        //自定义注解中的属性。相当于@MyAnno4Swagger(value="")
        String value() default "";
    }

## 自定义实体： ##

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    import java.io.Serializable;
    import java.util.Objects;
    
    /**
    * @ApiModel - 描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的返回值类型时，
    * 此注解被解析
    */
    	@ApiModel(value = "自定义实体-MyEntity",description = "MyEntity存储用户数据")
        public class MyEntity implements Serializable {
    
            private static final long serialVersionUID = 1L;
            
            @ApiModelProperty(value = "主键",name = "主键（id）",
                              required = false,example = "1",hidden = false
                             )
            private String id;
    
            @ApiModelProperty(value = "姓名",name = "姓名(name)",
                              required = true,example = "王小怪",hidden = false
                             )
            private String name;
    
            @ApiModelProperty(value = "密码",name = "密码(pwd)",
                              required = true,example = "pwd-123",hidden = false
                             )
            private String password;
    
            @Override
            public boolean equals(Object o) {
                if (this == o) return true;
                if (o == null || getClass() != o.getClass()) return false;
                MyEntity myEntity = (MyEntity) o;
                return id.equals(myEntity.id) && name.equals(myEntity.name) && password.equals(myEntity.password);
            }
    
            @Override
            public int hashCode() {
                return Objects.hash(id, name, password);
            }
    
            public MyEntity(){}
    
            public MyEntity(String id, String name, String password) {
                this.id = id;
                this.name = name;
                this.password = password;
            }
    
            public String getId() {
                return id;
            }
    
            public void setId(String id) {
                this.id = id;
            }
    
            public String getName() {
                return name;
            }
    
            public void setName(String name) {
                this.name = name;
            }
    
            public String getPassword() {
                return password;
            }
    
            public void setPassword(String password) {
                this.password = password;
            }
        }

## Controller示例： ##

[swagger]: https://so.csdn.net/so/search?q=swagger&spm=1001.2101.3001.7020
[a364d6cc6fe708e746bf8c15ff9adace.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/31/36c0e99b4f544967a731ba3dce9a9c8c.png
[666138127a95ee041dc14bb3e84654ab.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/31/7586c04fd4134516855e46720d1fb493.png