课程名称：Spring Cloud 进阶 Alibaba 微服务体系自媒体实战
课程章节： 第2章 架构后端项目
主讲老师： 风间影月
课程内容
在正常的工作当中，后端需要编写对应的接口文档。而传统的通过Word的方式存在一些格式难以控制、更新慢等一些问题。所以引入在线的Swagger接口文档。
项目嵌入Swagger的具体步骤为：
引入依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> </dependency>
创建配置类com.imooc.api.config.Swagger2
package com.imooc.api.config;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig2 {
// 配置swagger2核心配置 docket
@Bean
public Docket createRestApi() {
Predicate<RequestHandler> adminPredicate = RequestHandlerSelectors.basePackage("com.imooc.admin.controller");
Predicate<RequestHandler> articlePredicate = RequestHandlerSelectors.basePackage("com.imooc.article.controller");
Predicate<RequestHandler> userPredicate = RequestHandlerSelectors.basePackage("com.imooc.user.controller");
Predicate<RequestHandler> filesPredicate = RequestHandlerSelectors.basePackage("com.imooc.files.controller");
return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2
.apiInfo(apiInfo()) // 用于定义api文档汇总信息
.select()
.apis(Predicates.or(adminPredicate, articlePredicate, userPredicate, filesPredicate))
.paths(PathSelectors.any()) // 所有controller
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("慕课新闻·自媒体接口api") // 文档页标题
.contact(new Contact("imooc",
"https://www.imooc.com",
"abc@imooc.com")) // 联系人信息
.description("专为慕课新闻·自媒体平台提供的api文档") // 详细信息
.version("1.0.1") // 文档版本号
.termsOfServiceUrl("https://www.imooc.com") // 网站地址
.build();
}
}为controller添加api注解：
@Api(value = "controller标题", tags = {"xx功能controller"})为接口添加注解：
@ApiOperation(value = "hello方法", notes = "hello方法", httpMethod = "GET")
课程收获
注解详情
@Api
用在类上，该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性
tags API分组标签。具有相同标签的API将会被归并在一组内展示。
value 如果tags没有定义，value将作为Api的tags使用
description API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用
@ApiOperation
在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：
value 对操作的简单说明，长度为120个字母，60个汉字。
notes 对操作的详细说明。
httpMethod HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。
@ApiImplicitParams
用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。
@ApiImplicitParam
对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：
name 参数名称
value 参数的简短描述
required 是否为必传参数
dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。
@ApiParam
增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有
required 是否为必传参数，默认为false
value 参数简短说明