- 使用步骤

• 一.下载依赖 去maven官网收索springfox-swag

  
  图片.png

介绍

在以往的web项目开发中，大家会经常的使用postman来测试接口和使用文档来编写接口，大量的重复劳动，相信大家已经厌烦，为了解决它使大家能有更多的时间专注于编码，一款叫做swagger2的软件诞生了，只需要导入依赖，并在控制层加上@Api这个注解就能快速生成一个接口文档，并能像postman一样对接口进行测试。

快速入门

导入依赖后直接加上@EnableSwagger2 就可以了

第一步、在pom中导入依赖

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

第二步、在Application中加入注解@EnableSwagger2

第三步、打开URL

打开URL，URL格式为：你的端口+/swagger-ui.html

例如：http://localhost:9011/swagger-ui.html

[图片上传失败...(image-a2cf79-1617613050501)]

测试接口

1、点开其中一个接口

[图片上传失败...(image-40653d-1617613050501)]

2、输入ID点击Try it out

[图片上传失败...(image-5baa0d-1617613050501)]

3、查看测试结果

[图片上传失败...(image-5896fc-1617613050501)]

定制化你的接口文档

如果觉得页面内容太少了，对它默认的内容不太满意，需要加点描述使它更加详细，也可以选择自己加上一些描述内容。

编写一个配置类

package com.tang.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;

//标注此类是配置类  里面有@Component吧自身注入到spring进行管理
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    // 扫描所有带@ApiOperation注解的类
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tang.swagger.controller")) //包名
                .build();
    }

    @Bean
    public Docket api1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tang.swagger.controller"))
                .build();
    }

    //api接口作者相关信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("文档作者信息", "", "XXX@qq.com");
        ApiInfo apiInfo = new ApiInfoBuilder().license("").title("唐的SwaggerApi").description("接口文档").contact(contact).version("3.0").build();
        return apiInfo;
    }


}

@Configuration
public class SwaggerConfig {
// 扫描所有带@ApiOperation注解的类
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}

//api接口作者相关信息
private ApiInfo apiInfo() {
Contact contact = new Contact("文档作者信息", "", "XXX@qq.com");
ApiInfo apiInfo = new ApiInfoBuilder().license("").title("标题").description("接口文档").contact(contact).version("3.0").build();
return apiInfo;
}
}</pre>

[图片上传失败...(image-7cd9f8-1617613050501)]

在Controller类和方法上加注解

在类上加@Api(description = "这是我全部的get方法")

在方法上加@ApiOperation(value = "根据ID查询一个品牌")

图片.png 图片.png

注解

--value 对资源的标签名

--description 描述

@ApiOperation ：对方法的注解

--value 对资源的标签名

--notes 对方法操作的描述

@ApiImplicitParams ：对多个参数的描述的集合

@ApiImplicitParam：在@ApiImplicitParams里面

--name 属性字段名

--value 属性字段含义

--required 是否必填（true/false）

--paramType 参数位置（"query"为参数放置url,"body"为post方法放在body里...）

 paramType：表示参数放在哪个地方
    header-->请求参数的获取：@RequestHeader(代码中接收注解)
    query-->请求参数的获取：@RequestParam(代码中接收注解)
    path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
    body-->请求参数的获取：@RequestBody(代码中接收注解)
    form（不常用）

--dataType 参数类型（"String"、"int"...）

@ApiModel ：对实体类的描述

@ApiModelProperty ：对实体字段的描述

--name 属性名称

--value 属性描述

--hidden 是否不再swagger页面展示（true/false）</pre>