swagger常用注解
@ApiModel("") -----------------写在实体类模块的上方,对实体类进行说明
@Api(tags = “xxxx”)----------写在Controller模块的上方,对Controller模块进行说明
@ApiParam("")-----------------写在传入参数的前方,对参数进行说明
@ApiOperation("")------------写在Controller模块内的方法上面,对方法进行说明
swagger的使用
1、导入依赖
注意如果要使用新版本的swagger3.0.0,导包被简化成一个,而不像之前要导两个
<!--开启swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
以下是swagger2,x版本的依赖包。swagger2和swagger3有在使用上有一些的区别,下面我都是按照新版本的swagger3来测试
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger- ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、需要写一个swagger的配置类
// 只有扫描controller目录才不会出现basis error
@Configuration
// 不需要添加Enable注解了
public class SwaggerConfig {
// 配置Docket的bean实例
@Bean
public Docket docket() {
// 调用apiInfo
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
/*select-api-paths是固定搭配*/
.select()
/**
* apis():指定扫描的接口
* RequestHandlerSelectors:配置要扫描接口的方式
* basePackage:指定要扫描的包
* any:扫面全部
* none:不扫描
* withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
* withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
*/
// 根据目录名进行修改
// 只有扫描controller目录才不会出现basis error
.apis(RequestHandlerSelectors.basePackage("com.controller"))
/**
* paths():过滤路径
* PathSelectors:配置过滤的路径
* any:过滤全部路径
* none:不过滤路径
* ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
* regex:过滤指定路径:按照String的matches方法进行匹配
*/
.paths(PathSelectors.any())
.build();;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xxx") // 标题
.description("本文档描述了xxx后端接口文档") // 描述
.version("1.0") // 版本
.build(); // 创建
}
}
3、访问测试 :http://localhost:9090/swagger-ui/index.html [注意是/index.html而不是原来的直接html] ,可以看到swagger的界面。这个端口号要根据自己的后端端口号进行修改。这样就可以进入swagger的界面了。