【springboot】使用swagger生成接口文档

1. 添加依赖

XML 复制代码
      <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.6.0</version>
      </dependency>

这里我老是添加不上这个依赖,搜索了下发现阿里云公共仓库中没有这个依赖,所以一直找不到。(阿里云仓库搜索

于是修改了下maven的setting文件,添加了阿里云的中心仓库的镜像。

XML 复制代码
      <mirror>
          <id>aliyunmaven-central</id>
          <mirrorOf>*</mirrorOf>
          <name>阿里云中心仓库</name>
          <url>https://maven.aliyun.com/repository/central</url>
      </mirror>

2. 配置swagger

java 复制代码
@Configuration
@ComponentScan
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API文档")
                        .version("1.0")
                        .description("Spring Boot 3.2.8项目的API文档")
                        .contact(new Contact().name("huan").email("developer@example.com"))
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://example.com/docs"));
    }
}

配置完以上内容,访问localhost:8080/swagger-ui/index.html,可以跳转以下页面。

3. 使用Swagger注解来描述API

控制器类

java 复制代码
@RestController
@RequestMapping("resfood")
//@Tag注解用于为API接口分组,并提供分组的名称和描述
@Tag(name = "菜品api",description = "菜品管理相关接口")
public class ResfoodController {
    @Autowired
    private ResfoodService resfoodService;

    //{fid}结合@PathVariable实现rest风格url
    @GetMapping("getById/{fid}")
    public Map<String,Object> getById(
            // @PathVariable注解用于将请求路径中的参数绑定到方法参数上
            @PathVariable Integer fid){
        Map<String,Object> map = new HashMap<>();
        Resfood resfood = null;
        try {
            resfood = resfoodService.getById(fid);
        }catch (Exception e){
            e.printStackTrace();
            //设置状态码和提示信息
            map.put("code",0);
            map.put("msg","查询失败"+e.getCause());
            return map;
        }
        map.put("code",1);
        map.put("obj",resfood);
        return map;
    }
}

一些注解

  • @Tag注解:用于为API接口分组,并提供分组的名称和描述。

控制类

显示效果

  • @Operation注解:提供关于该方法操作的简要和详细描述。

控制类

显示效果

  • @ApiResponse注解:提供该方法的响应信息,如HTTP 响应码、响应的描述信息、响应的内容等。
    • @Content注解:描述响应的内容。
    • @Schema注解:指定响应内容的模式。

控制类方法

显示效果

4. 访问Swagger UI

再次访问localhost:8080/swagger-ui/index.html,发现多了一些东西。

展开可以看到以下信息。

5. 测试

可以在swagger ui中发送测试数据,测试获得的响应json是否正确。打开某个请求路径,使用Try it out 按件后可以设置要测试的参数。

Execute后可以得到响应结果。

响应结果。

相关推荐
岁忧2 分钟前
(LeetCode 每日一题) 1865. 找出和为指定值的下标对 (哈希表)
java·c++·算法·leetcode·go·散列表
YuTaoShao5 分钟前
【LeetCode 热题 100】240. 搜索二维矩阵 II——排除法
java·算法·leetcode
考虑考虑1 小时前
JDK9中的dropWhile
java·后端·java ee
想躺平的咸鱼干1 小时前
Volatile解决指令重排和单例模式
java·开发语言·单例模式·线程·并发编程
hqxstudying2 小时前
java依赖注入方法
java·spring·log4j·ioc·依赖
·云扬·2 小时前
【Java源码阅读系列37】深度解读Java BufferedReader 源码
java·开发语言
春生野草2 小时前
关于SpringMVC的整理
spring
Bug退退退1233 小时前
RabbitMQ 高级特性之重试机制
java·分布式·spring·rabbitmq
小皮侠3 小时前
nginx的使用
java·运维·服务器·前端·git·nginx·github
Zz_waiting.3 小时前
Javaweb - 10.4 ServletConfig 和 ServletContext
java·开发语言·前端·servlet·servletconfig·servletcontext·域对象