【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("[email protected]"))
                        .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后可以得到响应结果。

响应结果。

相关推荐
前行的小黑炭3 分钟前
设计模式:为什么使用模板设计模式(不相同的步骤进行抽取,使用不同的子类实现)减少重复代码,让代码更好维护。
android·java·kotlin
Java技术小馆8 分钟前
如何设计一个本地缓存
java·面试·架构
XuanXu1 小时前
Java AQS原理以及应用
java
风象南4 小时前
SpringBoot中6种自定义starter开发方法
java·spring boot·后端
mghio13 小时前
Dubbo 中的集群容错
java·微服务·dubbo
咖啡教室17 小时前
java日常开发笔记和开发问题记录
java
咖啡教室18 小时前
java练习项目记录笔记
java
鱼樱前端18 小时前
maven的基础安装和使用--mac/window版本
java·后端
RainbowSea19 小时前
6. RabbitMQ 死信队列的详细操作编写
java·消息队列·rabbitmq