一、swagger简介
1、前后端分离开发
2、简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的Web 服务
它的主要作用是：
- 使得前后端分离开发更加方便，有利于团队协作。（实际开发中，接口文档的内容会不停的发生变化，如果没有及时更新接口文档，那么前后端就不能及时同步信息。我们通过在线的接口文档swagger，这样前后端工程师都遵守swagger就行了，只要接口文档发生了变化，就会实时更新。）
- 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
- 功能测试
Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。
二、SpringBoot集成Swagger
1、引入依赖
在common模块和model模块中引入该依赖。在common模块中引入是因为要实现自动配置，因为只要有微服务依赖了common工程，自定义自动配置类就能生效，就可以使用swagger。在model模块中引入是因为实体类中需要使用swagger的注解。
io.springfox
springfox-swagger2
io.springfox
springfox-swagger-ui
只需要在common模块中进行配置即可，因为其他微服务工程都直接或间接依赖即可。
2、在common模块中添加自动配置类
在common模块中添加SwaggerConfiguration配置类，如下：
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 springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.heima"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInfo() {
Contact contact = new Contact("黑马程序员","","");
return new ApiInfoBuilder()
.title("黑马头条-平台管理API文档")
.description("黑马头条后台api")
.contact(contact)
.version("1.0.0").build();
}
}
Contact中定义了联系人的信息。实际开发中，我们只需要修改配置类的信息即可。
3、common模块中的resources目录中新增以下目录和文件
文件：resources/META-INF/Spring.factories
spring.factories内容如下：
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.heima.common.swagger.SwaggerConfiguration
注意：1）、值为SwaggerConfiguration配置类的全限定类名。2）、spring.factories文件中多个自定义配置类用逗号分隔。
4、添加注解
Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数的描述信息
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数的描述信息
@ApiImplicitParam属性：
属性取值作用paramType 查询参数类型path 以地址的形式提交数据query 直接跟参数完成自动映射赋值body 以流的形式提交 仅支持POST header 参数在request headers 里边提交form 以form表单的形式提交 仅支持POST dataType 参数的数据类型 只作为标志说明，并没有实际验证Long String name 接收参数名value 接收参数的意义描述required 参数是否必填true 必填false 非必填defaultValue 默认值
我们在ApUserLoginController中添加Swagger注解，代码如下所示：
@RestController
@RequestMapping("/api/v1/login")
@Api(value = "app端用户登录", tags = "ap_user", description = "app端用户登录API")
public class AppUserLoginController {
@Autowired
private ApUserService apUserService;
@PostMapping("/login_auth")
@ApiOperation("用户登录")
public ResponseResult login(@RequestBody LoginDto loginDto){
ResponseResult result = apUserService.login(loginDto);
return result;
}
}
给实体类添加注解
@Data
public class LoginDto {
@ApiModelProperty(value = "手机号",required = true)
private String phone;
@ApiModelProperty(value = "密码",required = true)
private String password;
}
5、启动微服务器
访问地址：http://localhost:端口/swagger-ui.html ，进入如下界面：
我们在models中可以看到加了swagger注解的实体类，password和phone带*号表示必须输入。
点击接口如下所示：
返回结果如下：
Original: https://www.cnblogs.com/zwh0910/p/16539378.html
Author: 周文豪
Title: SpringBoot集成Swagger
原创文章受到原创版权保护。转载请注明出处：https://www.johngo689.com/541120/
转载文章受原作者版权保护。转载请注明原作者出处！