接口文档配置

最新推荐文章于 2023-02-13 00:57:53 发布

码上学习！Go٩( 'ω' )و

最新推荐文章于 2023-02-13 00:57:53 发布

阅读量542

点赞数

文章标签：学习

本文链接：https://blog.csdn.net/m0_58269982/article/details/127901910

版权

一、Swagger2

官网：https://swagger.io/

介绍：

号称世界上最流行的Api框架；
RestFul Api文档在线自动生成工具=》Api文档与API定义同步更新；
直接运行，可以在线测试API接口；
支持多种语言：Java，Php...

SpringBoot集成Swagger2

在项目中使用Swagger需要Springbox（1、swagger2；2、ui ）

1、在maven（官网：https://mvnrepository.com/）中查找相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、配置Swagger ==> SwaggerConfig

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

3、运行测试，访问路径：http://localhost:8080/swagger-ui.html

运行报错 “ Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException ”

原因：版本问题。springboot高版本（2.6.x）和swagger2的低版本（2.9.2）不兼容，将springboot改为低版本如2.1.x，2.4.x等

4、配置swagger信息

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

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Sugar","https://swagger.io/","3499832640@qq.com");
        return new ApiInfo(
                "Swagger学习笔记",
                "Study!!!!!!!!!",
                "v1.0",
                "https://swagger.io/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

5、swagger配置扫描接口

//配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable:是否启动swagger，默认为true，即启动
                .enable(false)
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                //paths():过滤什么路径
                .paths(PathSelectors.ant("/kuang/**"))
                .build()
                ;
    }

Swagger在生产环境中使用，在发布时不使用？

判断是否是生产环境 flag=false
注入enable（flag）

//设置要显示的swagger环境
        Profiles profiles=Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag=environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                //paths():过滤什么路径
                .paths(PathSelectors.ant("/kuang/**"))
                .build()
                ;
    }

6、配置API文档的分组

.groupName("Form")

如何配置多个分组；多个Docket实例即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

总结：

我们可以通过Swagger给一些比较难理解的属性或接口，增加注释信息

接口文档实时更新

可以在线测试

【注意点】在正式发布的时候，一定要关闭Swagger！！！处于安全以及节省内存的考虑！

二、Knife4j （推荐）

官网：https://doc.xiaominfo.com/

Knife4j是一款可以提供在线API文档的框架，是基于Swagger2框架实现的。

框架适配

Spring MVC
Spring Boot 2.2、2.3、2.4、2.5、2.6、2.7

SpringBoot集成knife4j

1、导入依赖

<!--引入Knife4j的官方start包-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <!--使用Swagger2-->
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2、配置Knife4j==> Knife4jConfig

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown语法
                .description("# Knife4j RESTful APIs")
                .termsOfServiceUrl("https://doc.xiaominfo.com/")
                .contact("xiaoymin@foxmail.com")
                .version("1.0")
                .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3、接口测试

@Api("测试")
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

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

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}