使用Knife4j做API文档，效果更好

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案。

快速开始(Spring Boot 2 + OpenAPI2)

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：

<!--引入Knife4j的官方start包,该指南选择Spring Boot版本<3.0,开发者需要注意-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

第二步：创建Swagger配置依赖，代码如下：：

@Configuration
@EnableSwagger2WebMvc
@Profile({"dev", "test"})
public class Knife4jConfiguration {

     @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 指定认证相关信息
                .securitySchemes(Collections.singletonList(apiKey()))
                .select()
                // 指定扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.google.controller"))
                .paths(PathSelectors.any())
                .build()
                // 指定路径前缀
                .pathMapping(pathMapping())
                .apiInfo(apiInfo());
    }

    private String pathMapping() {
        if (EnvUtil.isDevEnv() || !OSUtil.isBigoServer()) {
            return "/";
        }
        return "/xxx-xxxx";
    }

    private ApiKey apiKey() {
        return new ApiKey("Token", "Token", "header");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("官网API")
                .description("官网API.")
                .version("1.0.0")
                .contact(new Contact("Your Name", "https://example.com", "your-email@example.com"))
                .build();
    }
}

第三步:新建一个接口Controller类，如下：

@Api(tags = "首页模块")
@RestController
public class IndexController {

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

万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果http://localhost:8080/doc.html