Swagger

最新推荐文章于 2024-08-09 07:47:27 发布

原创最新推荐文章于 2024-08-09 07:47:27 发布 · 157 阅读

CC 4.0 BY-SA版权

这篇博客介绍了如何在SpringBoot项目中集成Swagger，实现RESTful API的在线文档自动生成和接口测试。通过引入springfox-swagger2和springfox-swagger-ui依赖，配置SwaggerConfig，并使用Docket进行详细设置，包括扫描接口、配置信息、启用Swagger以及分组管理。Swagger使得API文档与代码同步更新，方便开发者快速理解和测试接口。

Swagger

RestFul API 文档在线自动生成工具 --> API文档与API定义同步更新

可直接运行，可以在线测试API接口

支持多种语言：（JAVA、PHP…)

在项目中使用Swagger 需要 springbox

swagger2

SpringBoot 集成Swagger

1.新建SpringBoot-web项目

2.导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!--3.0.0版本需要额外导入-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

3.编写工程

4.配置Swagger

java/config/SwaggerConfig

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}

5.测试运行

访问地址：http://localhost:8080/swagger-ui/index.html

配置Swagger

Swagger的bean实例：Docket

//配置 Swaager 的 Docket 的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

配置Swagger信息

    //配置Swagger信息

    //apiInfo
    public ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("rz","","");

        return new ApiInfo("SwaggerApi文档",  //文档标题
                "Swagger学习",  //描述
                "1.0",  //版本
                "urn:tos", //
                 contact,  //作者信息
                "Apache 2.0", //开源版本号 
                "http://www.apache.org/licenses/LICENSE-2.0", //
                new ArrayList()); //
    }

配置Swagger扫描接口

Docket.select()

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()               .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.ant("/*"))
                .build();
    }

    //配置Swagger信息

其中：

apis（）

RequestHandlerSelectors配置要扫描接口的方式
basePackage:指定要扫描的包
any:扫描全部
none:不扫描
withClassAnnotation:扫描类上的注解，即withClassAnnotation(xxx.class) 只要扫到xxx，则将其归为需要的对象
withMethodAnntation:扫描方法上的注解

paths()过滤
PathSelectors
ant():只扫描带有xxx的接口

配置是否启动Swaager

enable() 是否启动，false 则不能在浏览器中访问

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .build();
    }

配置文档分组

groupName()

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("WOW")
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .build();
    }

配置多个文档分组

配置多个Bean对象即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("2");
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("3");
    }

实体类配置

只要在接口，方法中返回值存在实体类，则就会被扫描到Swagger中

eg：

pojo/User

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("名字")
    String name;
    @ApiModelProperty("性别")
    int age;
}

controller

@PostMapping("/user")
    public User user(){
        return new User();
    }