配置swagger文档

项目开发实现前后端分离，sagger能提供强大的页面测试功能，来让开发人员调试每个写好的接口

目录

前言

1.引入swagger依赖

2.创建Swagger配置类

3.使用Swagger注解对类、方法、参数进行描述

 4.访问地址

总结

---

---

前言

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

使用步骤

1.引入swagger依赖

代码如下（示例）：

        <!--swagger-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

2.创建Swagger配置类

代码如下（示例）：

@Configuration  //声明该类为配置类
@EnableSwagger2 //开启Swagger注解
public class SwaggerConfig {

    //配置文档属性
    private ApiInfo getApiInfo(){
      return   new ApiInfoBuilder().title("文档标题")
                .description("文档描述")
                .version("API版本")
                .termsOfServiceUrl("团队链接")
                .build();
    }

    //创建文档配置对象
    @Bean
    public Docket docket(){
                //文档描述类型：DocumentationType.SWAGGER_2
                //文档描述：getApiInfo()
      return   new Docket(DocumentationType.SWAGGER_2).apiInfo(this.getApiInfo())
                  //组名：group
                .groupName("group")
                //返回 ApiSelectorBuilder 
                .select()
                .build();
    }
}

3.使用Swagger注解对类、方法、参数进行描述

@ApiModel(description = "对类的详细描述",value = "类名")
@ApiModelProperty(value = "字段说明",required = "是否必填默认false")
@Api(tags = "说明该类的作用，可以在UI界面上看到的注解")
@ApiOperation(value = "接口说明",response = "接口返回参数类型", notes = "接口发布说明"）
		value：对该操作进行简单的描述，尽量控制在120字符以内。
		notes：对操作的详细描述。
		tags：用来给操作打标签，Swagger UI将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。（就是分组）
		
@ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "参数名", value = "参数说明", required = "是否必填，默认false"),
    })
@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：参数的默认值

API	使用位置	作用范围
@ApiModel	用在返回对象类上（实体类）	描述返回对象的意义
@ApiModelProperty	用在参数对象的字段上	对象属性
@Api	用在Controller类上	协议集描述
@ApiOperation	用 在controller方法上	接口描述
@ApilmplicitParams	用在controller方法上	非对象参数集
@ApilmplicitParam	用在@ApilmplicitParams的方法里边	非对象参数描述

 4.访问地址

http://localhost:端口/swagger-ui.html

---

总结

以上就是今天要讲的内容，本文仅仅简单介绍了swagger的使用，而swagger在开发人员开发项目中提供了很大的方便。