SpringBoot---------集成Swagger(SpringFox,SpringDoc两方案)

 SpringFox方案(已停止维护)

第一步：引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

第二步：添加配置文件

package com.example.carcentservice.config;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class swaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档标题")
                .description("API 详细描述")
                .version("1.0")
                .build();
    }
}

如果SpringBoot版本较低，出现报错的，在yml配置文件中加入：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

第三步：常用注解

@Controller
@Api(tags = "用户管理")
public class BasicController {

    @GetMapping("/hello")
    @ResponseBody
    @Operation(summary = "hello", description = "hello")
    public String hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return "Hello " + name;
    }

    @PutMapping("/user")
    @ResponseBody
    public User user() {
        User user = new User();
        user.setName("theonefx");
        user.setAge(666);
        return user;
    }

    @DeleteMapping("/save_user")
    @ResponseBody
    public String saveUser(User u) {
        return "user will save: name=" + u.getName() + ", age=" + u.getAge();
    }

    @PutMapping("/html")
    public String html() {
        return "index.html";
    }
}

第四步：进入localhost:8080/swagger-ui/index.html中进行接口调试

 SpringDoc方案(支持OpenAPI 3.0，兼容Boot 2.x/3.x)

 第一步：引入依赖

<!--  SpringBoot 3.x   -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>


<!--  SpringBoot 2.x   -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

第二步：添加配置文件

package com.example.carcentservice.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API文档")
                        .version("1.0")
                        .description("SpringBoot项目接口文档")
                        .termsOfService("https://example.com"));
    }
}

第三步：常用注解

@Controller
@Tag(name = "用户管理", description = "用户相关接口")
public class BasicController {

    @GetMapping("/hello")
    @ResponseBody
    @Operation(summary = "hello", description = "hello")
    public String hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return "Hello " + name;
    }

    @PutMapping("/user")
    @ResponseBody
    public User user() {
        User user = new User();
        user.setName("theonefx");
        user.setAge(666);
        return user;
    }

    @DeleteMapping("/save_user")
    @ResponseBody
    public String saveUser(User u) {
        return "user will save: name=" + u.getName() + ", age=" + u.getAge();
    }

    @PutMapping("/html")
    public String html() {
        return "index.html";
    }
}

第四步：进入localhost:8080/swagger-ui/index.html中进行接口调试