一、swagger简介

这里我在网上查了发现的大部分介绍swagger都是长篇大论,太过官方,这里简单概括:swagger是一款能够快速生成接口文档,接口注释的优秀工具

二、springboot整合swagger

1、导入pom

      <!-- springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、编写配置类,将Docket注入容器中

这里自己可以重写一个ApiInfo,更改属于自己的swagger简介

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //作者信息
    public static final Contact DEFAULT_CONTACT = new Contact("kexing", "https://kexing.site/", "1600342330@qq.com");

    //swagger信息
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "kexing's swagger 文档",
                "不试试怎么知道",
                "v1.0",
                "https://kexing.site/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }

    //配置swagger的Docket实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("可星")
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage:执行扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation():扫描类上的注解
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("site.kexing"))
                .build();
    }

swagger

三、设置sawgger的运行环境、多人协作

@Bean
    public Docket docket(Environment environment){
        /**
         * 希望swagger在自己设置的环境中运行
         */
        //设置swagger的环境
        Profiles profiles = Profiles.of("dev","test");
        //判断当前环境是否在swagger设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("可星")
                .enable(flag)
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage:执行扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation():扫描类上的注解
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("site.kexing"))
                .build();
    }

通过profiles可以设置swagger能运行的环境,一般是开发和测试,当项目上线就不允许访问了,然后通过environment.acceptsProfiles可以判断swagger的环境与此时的项目环境是否一致,返回一个boolean,最后通过enable(flag)即可控制swagger的开启

注入多个bean,通过groupName设置组名,然后设置一些上面的相关配置即可完成多人协作

    //多人协同开发 注入多个docket
    @Bean
    public Docket guofubing_docket(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("guofubing");
    }

四、生成接口文档、接口测试

User

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

@ApiModel设置实体类的注释信息,@ApiModelProperty设置属性的注释信息

UserController

@Controller
@Api(tags = "用户控制器")
public class UserController {
    //只要接口返回了实体类 swagger就会有显示
    @ResponseBody
    @PostMapping(value = "/user")
    public User getUser(){
        return new User("kexing","123");
    }

    @ResponseBody
    @GetMapping(value = "/getuname")
    public String getUsername(String username){
        return username;
    }

    @PostMapping(value = "/topage")
    @ApiOperation(value = "返回测试视图")
    public String toPage(){
        return "test";
    }
}

控制器也可以设置注释信息,通过@Api@ApiOperation注解完成
swagger

swagger

最后修改:2021 年 11 月 15 日 05 : 16 PM
如果觉得我的文章对你有用,请随意赞赏