swagger总结

目录

Swagger前言

SpringBoot集成Swagger2

导入依赖

在controller中写一个controller工程

配置swagger文件

配置swagger

Swagger配置扫描接口

RequestHandlerSelectors的静态方法

生产环境使用Swagger

配置API文档的分组

models

注释用注解

Swagger前言

• 号称世界上最流行的api框架
• RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
• 可以通过swagger注解给难理解的接口或属性增加注释信息
• 直接运行，可以在线测试Api接口(try it out)
• 支持多种语言：（Java、PHP……）

官网：https://swagger.io/

SpringBoot集成Swagger2

注意：使用的springboot版本为2.5.1不然容易报空指针

导入依赖

    <dependencies>
        <!--web项目-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--springboot测试类-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!--swagger2依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger的ui界面-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>

在controller中写一个controller工程

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello world";
    }
}

配置swagger文件

@Configuration
//开启swagger2注解
@EnableSwagger2
public class SwaggerConfig {
    
}

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

配置swagger

注意：Swagger有一个bean的实例Docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置docket的实例
    @Bean
    public Docket docket(){
        //作者信息
        Contact contact = new Contact("大神", "https://www.baidu.com", "12345@qq.com");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfo(
                        "大神的文档",//标题
                        "简单的描述",//描述
                        "1.0",//版本号
                        "https://www.baidu.com",//team组织网址
                        contact,
                        "Apache 2.0",//lincense
                        "http://www.apache.org/licenses/LICENSE-2.0",//lincenseUrl
                        new ArrayList()));
    }
}

Swagger配置扫描接口

    //配置docket的实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //配置是否启动swagger
                .enable(false)
                //下面三行同时使用，用于配置扫描接口
                .select()
                //配置要扫描接口的方式
                //扫描下面controller包下的接口
                .apis(RequestHandlerSelectors.basePackage("cn.tedu.swagger.controller"))
                //过滤其他路径，只扫描hell0后面的路径
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }

RequestHandlerSelectors的静态方法

• any()：扫描全部
• none()：全不扫描
• basePackage("cn.tedu.swagger.controller")：扫描该包下的接口
• withMethodAnnotation(GetMapping.class)：扫描方法上被该注解标识的接口

生产环境使用Swagger

#application.properties文件内
#激活生产环境
spring.profiles.active=dev

#application-dev.properties文件内
server.port=8081

#application-pro.properties文件内
server.port=8082

    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境——里面传一个数组
        Profiles profiles = Profiles.of("dev","test");
        //若此环境属于上面的一种，那么返回true
        boolean b = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(b);
    }

配置API文档的分组

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //分组1
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("大神");
    }
    //分组2
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("大牛");
    }
}

models

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello world";
    }
    @PostMapping("hi")
    public User hi(){
        return new User();
    }
}

public class User {
    public String name;
    public Integer age;
}

注意：只要接口中返回了实体类，那么modles中就会有对应的实体类（实体类中的属性用public修饰ui中可见属性，其他修饰符不可见）

注释用注解

@RestController
public class HelloController {
    //注释接口的注解
    @ApiOperation("hello接口")
    @GetMapping("/hello")
    public String hello(){
        return "hello world";
    }
    @ApiOperation("hi接口")
    @PostMapping("hi")
    public User hi(){
        return new User();
    }
}

//注释实体类的注解
@ApiModel("user用户实体类")
public class User {
    //注释实体类属性的注解
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("用户密码")
    public Integer password;
}