swagger基本使用指南

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自动配置的，如果需要定制更详细的信息，可以使用注解。

使用注解

1. @Api
   1. 功能:描述controller类
   2. 注解位置:类
   3. 常用注解属性
      1. tags = "" // 描述此controller类
2. @ApiOperation
   1. 功能:描述一个方法或者一个API接口
   2. 注解位置:方法
   3. 常用注解属性
      1. value = "" // 描述方法
      2. notes = "" // 描述方法详细信息
3. @ApiImplicitParam
   1. 功能:描述方法或接口参数
   2. 注解位置: 方法
   3. 注解属性
      1. name = "" // 方法或接口的形参, 注意要与方法的参数名称相同
      2. value = "" // 对参数的描述
      3. paramType = "" // 参数传递方式，此属性的可选值 ["header", "query", "path", "body", "form"]
         1. header，使用@RequestHeader获取的参数
         2. query，使用@RequestParam获取的参数，常用于GET请求
         3. path，使用@PathVariable获取的参数
         4. body，使用@RequestBody获取的参数，常用于POST请求，对象参数
      4. dataType = "" // 参数类型，例如 string, int, ArrayList, POJO类
4. @ApiImplicitParams
   1. 功能:汇集多个参数
   2. 注解位置: 方法
   3. 注解属性
   1. @ApiImplicitParam组成的列表