一、Swagger对于实际开发过程中有什么用?
面向WEB应用的开发一定离不开前端和后端两个话题。一个优秀的,成熟的开发团队,无论是从学生时代的组队课程成设计,还是从公司里择选的程序员组成的开发团队,一定离不开分工明确,协同开发。在经过了需求分析后,后端根据业务逻辑实现相应的接口,前端自己模拟数据实现页面布局。Swagger在这其中充当前后端联系的胶水【接口文档】,后端在测试运行项目的时候,无需刻意编写对应接口的一些解释说明,参数、返回值说明,可以通过这个工具在线生成对应的模块以及对应接口说明,前端只需要通过浏览器访问就了解到方法的使用,发起请求需要哪些参数,或者接受数据时怎么使用。
Swagger官网: https://swagger.io/
二、Swagger效果图
访问连接是:http://ip地址:端口号/swagger-ui.html。
这里我是本地运行后端springBoot,所以访问url:http://localhost:8088/swagger-ui.html
对应模块视图:
用户模块的接口:
接口的参数以及返回情况:
三、如何配置使用swagger?
## 引入依赖pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
当然也可以自己去maven中下载自己想要的版本。https://mvnrepository.com/
编写配置文件,并开启相应服务
@Configuration
//@Configuration修饰的AppConfig是一个cglib的代理对象
// 所以@Configuration 保证了配置类的内部方法之间依赖调用时都从容器中获取bean
@EnableSwagger2
//开启swagger2
@EnableKnife4j
//开启knife4j(swagger+)
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.missbear.gradution.design.controller"))//扫描接口包
.paths(PathSelectors.any())//进一步完善接口扫描
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.contact(new Contact("负责人姓名","博客地址","邮箱联系"))//api 负责人联系信息
.title("基于云平台的开放式物联网创新实验教学系统")//swagger api页面的标题
.description("后端接口文档")//swagger api页面的描述
.termsOfServiceUrl("http://localhost:8088/")//服务地址
.version("1.0")//开发版本号
.build();
}
}
相关Api接口配置和说明作用如下:
注解 | 使用位置 | 用途 |
---|---|---|
@Api | 类/接口 | 描述类/接口主要用途 |
@ApiOperation | 方法 | 描述方法的用途 |
@ApiImplicitParam | 方法 | 用于描述接口的非对象参数 |
@ApiImplicitParams | 方法 | 用于描述接口的非对象参数集 |
@ApiIgnore | 类/方法/参数 | Swagger 文档不会显示拥有该注解的接口 |
@ApiModel | 参数实体类 | 可设置接口相关实体的描述 |
ApiModelProperty | 参数实体类属性 | 可设置实体属性的相关描述 |
四、注意,如果人为swagger界面不够友善,可以尝试swagger的升级版。
修改依赖导入:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索最新版本号-->
<version>3.0.3</version>
</dependency>
对应访问地址也发生变化:http://localhost:8088/doc.html
- 参考一:springBoot集成swagger2
- 参考二:Swagger2常用注解说明
代码参考:交通大学 物联网学长——朱学长