swagger 接口文档

pigcloud

重要说明

• 本章文档对应视频 📺 6.接口文档 swagger 使用

• 单体版本请求地址： http://pigx-gateway:9999/admin/swagger-ui.html

• 请求入口必须是 pigx-gateway:9999 这种形式， 而不是 ip:9999 ，不然跨域。

#接入调试

#1. 访问 swagger-ui 页面

• 访问http://pigx-gateway:9999/swagger-ui.html打开 swagger 页面。

#2.模拟登陆

#3.填写客户端信息

username: admin
password: JFat0Zdc
client_id: test
client_secret ： test

#新服务接入

#1.服务添加依赖

<dependency>
    <groupId>com.pig4cloud</groupId>
    <artifactId>pigx-common-swagger</artifactId>
</dependency>

#2.目标服务开启 OpenApi

• 在应用主类中增加@EnableOpenApi注解 并且填写当前应用的网关请求前缀

@EnableOpenApi("admin")
public class PigxAdminApplication {}

#3. 接口增加@SecurityRequirement

Controller 接口上边必须增加 @SecurityRequirement(name = HttpHeaders.AUTHORIZATION)

@Tag(description  = "connect", name =  "开放互联")
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)
public class ConnectController {}

#4. 重启网关服务 （微服务版本）

如果使用 pigx 微服务版本，需要在上述操作完成后 重启 pigx-gateway 服务，以重新加载 Swagger 服务列表。

#5.常用注解

详细注解可以参考:https://blog.csdn.net/weixin_44768189/article/details/115055784(opens new window)

#关闭 swagger 接口文档

• nacos/application-dev.yml 配置关闭属性

springdoc:
  api-docs:
    enabled: false

• SpringDocConfiguration 增加关闭配置