swagger的使用
文章目录
1.认识Swagger
2.swagger的使用
2.1 方式1
2.2 方式二(使用knife4j)
3.Swagger的常用注解
1.认识Swagger
(1)Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
(2)作用：
① 接口的文档在线自动生成。
② 功能测试。
2.swagger的使用
2.1 方式1
创建swagger一般都是为了所有模块都能使用，可以单独创建一个模块,在启动类上添加注解
@ComponentScan(basePackages = {“//可以扫描的包”})
（1）导入swagger需要的坐标
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <scope>provided </scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <scope>provided </scope> </dependency>
②创建配置类。
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName(“webApi”) .apiInfo(webApiInfo()) .select() .paths(Predicates.not(PathSelectors.regex(“/admin/.“))) .paths(Predicates.not(PathSelectors.regex(”/error.”))) .build(); } /** * 创建该API的基本信息（这些基本信息会展现在文档页面中） * 访问地址：http://项目实际地址/swagger-ui.html * @return */ private ApiInfo webApiInfo(){ return new ApiInfoBuilder() .title(“网站-课程中心API文档”) .description(“本文档描述了课程中心微服务接口定义”) .version(“1.0”) .contact(new Contact(“Helen”, “http://www.baidu.com”, “123@qq.com”)) .build(); } }
③输入http://ip地址:端口号/swagger-ui.html即可使用
2.2 方式二(使用knife4j)
knife4j是为java MVC框架集成Swagger生成Api文档的增强解决方案
（1）导入knife4j的maven坐标
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.2</version> </dependency>
（2）导入knife4j相关配置类
（3）设置静态资源，否则接口文档页面无法访问
@Slf4j @Configuration @EnableSwagger2 @EnableKnife4j public class WebMvcConfig extends WebMvcConfigurationSupport { // 设置静态资源映射 @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { log.info("开始进行静态资源映射..."); registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } @Bean public Docket createRestApi() { // 文档类型 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.itheima.reggie.controller"))//需要扫描的Controller包路径 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("瑞吉外卖") .version("1.0") .description("瑞吉外卖接口文档") .build(); } }
（4）在LoginCheckFilter中设置不需要处理的请求路径
//定义不需要处理的请求路径 String[] urls = new String[]{ "/doc.html", "/webjars/**", "/swagger-resources", "/v2/api-docs" };
（5）输入http://ip地址:端口号/doc.html即可访问
3.Swagger的常用注解
（1）@Api：用在类上，例如Controller,表示对类的说明
（2）@ApiModel：用在类上，通常是实体类，表示一个返回响应数据的信息
（3）@ApiModelProperty：用在属性上，描述响应类的属性
（4）@ApiOperation：用在请求方法上，说明方法的用途、作用
（5）@ApiImplicitParams：用在请求的方法上，表示一组参数的说明
（6）@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
（7）@ApiParam：可以作用在接口方法上面，以及接口方法中的参数位置的注解，其主要是用来给接口中的参数
定义相关参数说明，主要是为了帮助相关人员理解接口中每个参数的含义。
