如何進行swagger ui快速入門

這篇文章給大家介紹如何進行swagger ui快速入門，內容非常詳細，感興趣的小伙伴們可以參考借鑒，希望對大家能有所幫助。

快速啟動

1 引入相關依賴

<dependency>
    <groupId>com.yishuifengxiao.common</groupId>
    <artifactId>common-spring-boot-starter</artifactId>
    <version>4.1.2</version>
</dependency>

2 開啟配置

在配置文件中加入以下配置即可快速開啟 swagger-ui 功能。

yishuifengxiao.swagger.base-package= 需要掃描的控制器代碼的路徑

加入上述配置后即可通過 http://ip:port/doc.html 查看 swagger-ui 增強文檔。

也可以通過 http://ip:port/swagger-ui.html 查看 swagger-ui 原生文檔。

此外，也可以通過http://ip:port/v2/api-docs查看元數據

這里只是簡化了 swagger-ui 的掃描注解，對于軟件開發過程中必須 swagger-ui 其他 API 注解仍然不可省略。

下面是一個簡單的 swagger-ui 配置文檔示例

@Api(value = "【測試接口】測試接口", tags = {"測試接口"})
@Valid
@Controller
@RequestMapping
@Slf4j
public class WebConftroller  {

    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "登錄的用戶名"),
            @ApiImplicitParam(name = "loginIp", value = "登錄ip"),
            @ApiImplicitParam(name = "pass", value = "登錄結果,true表示成功，false失敗"),
            @ApiImplicitParam(name = "pageSize", value = "分頁大小,分頁的大小不能小于1,默認值為20"),
            @ApiImplicitParam(name = "pageNum", value = "當前頁的頁碼,頁碼的大小不能小于1，默認值為1")})
    @ApiOperation(value = "分頁查詢登錄記錄", notes = "分頁查詢登錄記錄")
    @GetMapping("/demo")
    @ResponseBody
    public Response<String> findPage(
        HttpServletRequest request, HttpServletResponse response,
        @RequestParam(value = "username", required = false) String username,
        @RequestParam(value = "loginIp", required = false) String loginIp,
        @RequestParam(value = "pass", required = false) Boolean pass,
        @RequestParam(name = "pageSize", defaultValue = "20", required = false) Integer pageSize,
        @RequestParam(name = "pageNum", defaultValue = "1", required = false) Integer pageNum) {

        return Response.suc();

    }

}

<br/>

特別鳴謝：

此項功能中的 doc.html 界面中功能使用到了刀哥的 swagger-bootstrap-ui 中的功能 ，在此特別感謝 刀哥 的大力支持，關于 swagger-bootstrap-ui 的詳細說明請參見刀哥的 swagger-bootstrap-ui 文檔

配置參數

# swagger-ui文檔的標題
yishuifengxiao.swagger.title=API接口文檔
# swagger-ui文檔描述
yishuifengxiao.swagger.description=易水風蕭 接口說明文檔
#swagger-ui 項目服務的url
yishuifengxiao.swagger.terms-of-service-url=http://www.yishuifengxiao.com/
# swagger-ui 文檔分組的名字
yishuifengxiao.swagger.group-name=default
# swagger-ui 文檔版本
yishuifengxiao.swagger.version=1.0.0
# 項目聯系人名字
yishuifengxiao.swagger.contact-user=yishuifengxiao
# 項目聯系的url
yishuifengxiao.swagger.contact-url=http://www.yishuifengxiao.com/
# 項目聯系郵箱
yishuifengxiao.swagger.contact-email=zhiyubujian@163.com

以上常規配置都有缺省默認值，用戶在使用 易水風蕭通用組件 時，如果沒有特別需要，使用默認配置即可。

進階配置

一般情況下，使用 swagger-ui 的常規配置即可滿足日常開發需要，但是在某些情況下，可能需要一些高級配置。如，需要通過在所有的 API 接口上批量加上一個默認參數，此時即可用通用組件的高級配置功能了。

yishuifengxiao.swagger.contact.auths[0].name=Authorization
yishuifengxiao.swagger.contact.auths[0].description=自定義必填請求頭
yishuifengxiao.swagger.contact.auths[0].modelRef=string
yishuifengxiao.swagger.contact.auths[0].parameterType=header
yishuifengxiao.swagger.contact.auths[0].required=false

上述示例配置在 API 文檔中的所有請求中批量添加了一個參數名為 Authorization 的請求頭參數。yishuifengxiao.swagger.contact.auths 是一個數組，可以添加多個配置。

關于如何進行swagger ui快速入門就分享到這里了，希望以上內容可以對大家有一定的幫助，可以學到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到。