Maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
SpringBoot配
新建Swagger2.java类,请确保放在能被SpringBoot扫描到的位置
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("controller包")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("springboot利用swagger构建api文档") .description("项目描述,代码地址 https://github.com/ljinlin41") .termsOfServiceUrl("https://github.com/ljinlin41") .version("1.0") .build(); } }
API Web地址
此时启动SpringBoot项目,浏览http://localhost:8080/swagger-ui.html,可以发现已经有了项目的API信息。但这些信息是swagger自动配置的,如果需要定制更详细的信息,可以使用注解。
使用注解
- @Api
- 功能:描述controller类
- 注解位置:类
- 常用注解属性
- tags = "" // 描述此controller类
- @ApiOperation
- 功能:描述一个方法或者一个API接口
- 注解位置:方法
- 常用注解属性
- value = "" // 描述方法
- notes = "" // 描述方法详细信息
- @ApiImplicitParam
- 功能:描述方法或接口参数
- 注解位置: 方法
- 注解属性
- name = "" // 方法或接口的形参, 注意要与方法的参数名称相同
- value = "" // 对参数的描述
- paramType = "" // 参数传递方式,此属性的可选值 ["header", "query", "path", "body", "form"]
- header,使用@RequestHeader获取的参数
- query,使用@RequestParam获取的参数,常用于GET请求
- path,使用@PathVariable获取的参数
- body,使用@RequestBody获取的参数,常用于POST请求,对象参数
- dataType = "" // 参数类型,例如 string, int, ArrayList, POJO类
- @ApiImplicitParams
- 功能:汇集多个参数
- 注解位置: 方法
- 注解属性
- @ApiImplicitParam组成的列表