spring boot 集成 swagger

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文档会列出所有请求类型接口。