spring boot 集成 swagger

介绍

swagger官网
优点
- 便于管理接口
- 便于测试接口

添加依赖

<!-- swagger -->
<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>

添加swagger配置类

@Configuration
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
				// 扫描接口包根路径
                .apis(RequestHandlerSelectors.basePackage("com.example.myproject"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("")
                .version("1.0")
                .build();
    }
}

修改启动类

添加@EnableSwagger2注解。

@SpringBootApplication
@EnableSwagger2
public class MyprojectApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(MyprojectApplication.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(MyprojectApplication.class, args);
    }
}

测试

访问 http://localhost:8089/swagger-ui.html 查看API文档。

注解

用于丰富API文档的内容（更详细的接口说明）。

对API的注解
- @Api ：将一个Controller（Class）标注为一个swagger资源（API）。
  - tags：API分组标签
  - value：如果tags没有定义，value将作为Api的tags使用
- @ApiOperation：在指定的（路由）路径上，对一个操作或HTTP方法进行描述。
  - value：对操作的简单说明，长度为120个字母，60个汉字
  - notes：对操作的详细说明
  - httpMethod：HTTP请求类型["GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]
  - code：默认为200
- @ApiImplicitParams：以数组方式存储@ApiImplicitParam注解。
- @ApiImplicitParam：描述API中单一参数。（该注解中paramType属性值与API方法参数获取使用的注解不一致，会影响参数的接收）
  - name:参数名称
  - value：参数的简短描述
  - required：是否为必传参数
  - dataType:参数类型
  - paramType：参数的传入（请求）类型["path", "query", "body", "header", "form"]
- @ApiParam：增加对参数的元信息说明。
  - required:是否为必传参数
  - value:参数简短说明
- @ApiResponses：以数组方式存储@ApiResponse注解。
- @ApiResponse：描述一个操作可能的返回结果。
  - code:HTTP请求返回码。
  - message:更加易于理解的文本消息
对Model的注解
- @ApiModel：对 model 类的注解。
  - value:model的别名，默认为类名
  - description:model的详细描述
- @ApiModelProperty：对 model 属性的注解。
  - value:属性简短描述
  - example:属性的示例值
  - required:是否为必须值

PS：使用@RequestMapping注解，需指明请求方法，否则默认情况下API文档会列出所有请求类型接口。