首頁 > Java > java教程 > 主體

SpringBoot專案整合Swagger與swagger-bootstrap-ui及常用註解有哪些

WBOY
發布: 2023-05-24 12:22:13
轉載
1945 人瀏覽過

    一、前言

    隨著網路專案前後端分離方式的流行,前端與後端交給不同的人員開發,專案溝通成本也隨之提高。

    主要表現在WebAPI介面的溝通,Swagger2 應運而生,它可以動態產生Api介面文檔,降低溝通成本,促進專案高效開發。

    下面討論Swagger2及swagger-bootstrap-ui在SpringBoot上的整合

    二、SpringBoot專案整合swagger

    1. 引入依賴

            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>
    登入後複製

    2 . 編寫設定檔

    可對照進行對應的修改

    @Configuration
    @EnableSwagger2
    @EnableSwaggerBootstrapUI
    @Profile({"dev","test"})
    public class Swagger2Config {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("") //指定分组,对应(/v2/api-docs?group=)
                    .pathMapping("") //base地址,最终会拼接Controller中的地址
                    .apiInfo(apiInfo())
                    .select()
                    //为当前包路径
    				// .apis(RequestHandlerSelectors.any())
                    .apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        //构建 api文档的详细信息函数
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title("XXX API对接文档")
                    .description("XX API对接文档") //描述
                    //创建人
                    .contact(new Contact("yuhei001", "https://blog.csdn.net/Yuhei0", "18616591658@163.com"))
                    //版本号
                    .version("1.0")
                    //描述
                    .description("API 描述")
                    .build();
        }
    }
    登入後複製

    3. 啟動存取頁面

    http://127.0.0.1:10086/swagger-ui.html

    SpringBoot專案整合Swagger與swagger-bootstrap-ui及常用註解有哪些

    三、SpringBoot專案整合swagger-bootstrap-ui

    在步驟二的基礎上進行如下操作

    1.引入依賴

    #
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.9.6</version>
            </dependency>
    登入後複製

    2.配置資源處理規則

    未配置的情況下,有可能存取封包error.9996。

    實作WebMvcConfigurer接口,或是WebMvcConfigurationSupport(老版的SpringBoot),實作addResourceHandlers方法,加上如下所示程式碼即可。

    @Configuration
    public class AppWebConfig extends WebMvcConfigurationSupport{
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决 doc.html 404 报错
            registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
    }
    登入後複製

    @Configuration
    public class AppWebConfig extends WebMvcConfigurationSupport{
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决 doc.html 404 报错
            registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
        }
    }
    登入後複製

    另外,也可以在啟動類別上進行實作重寫

    @SpringBootApplication
    public class XXXApplication  implements WebMvcConfigurer{
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
        }
    }
    登入後複製

    3.啟動存取頁面

    造訪http:// 127.0.0.1:10086/doc.html,相較swagger-ui.html來說,此文件更為清爽。

    SpringBoot專案整合Swagger與swagger-bootstrap-ui及常用註解有哪些

    四、Swagger常用註解介紹

    swagger透過註解產生介面文檔,包括介面名稱、請求方法、參數、返回資訊等等。

    1.Swagger2Config中相關swagger註解

    1.1 @EnableSwagger2 開啟Swagger

    作用於設定類別或啟動類別

    #1.2 @EnableSwaggerBootstrapUI 開啟SwaggerBootstrapUi增強功能

    作用於設定類或啟動類,若不使用增強功能,可不開啟。

    2.controller中相關swagger註解

    2.1 @Api:修飾整個類,描述Controller的作用

    value和tags皆為說明,可用tags代替value

    @Api(value = "保险公司列表查询", tags = {"保险公司列表查询"})
    登入後複製

    2.2 @ApiOperation() 用於方法;表示一個http請求的操作

    @ApiOperation(value = "信息员保存(注册)/更新", tags = {"信息員保存"}, notes = "messenger desc")
    登入後複製

    2.3 @ApiParam 用於方法,參數,欄位說明;表示對參數的新增元資料(說明或是否必填等)

    適用於單一參數

    @ApiParam(name="sdMessengerInfo",value="参数描述",required=true)
    登入後複製

    2.4 請求參數註解,可進行組合

    • #@ApiImplicitParams 用於方法,包含多個@ApiImplicitParam

    • @ApiImplicitParam 為方法,表示單獨的請求參數

    適用於對多個參數進行描述

    範例:

    // 组合使用
    @ApiImplicitParams ({
        @ApiImplicitParam(name = "id", value = "参数中文描述", required = true)
    })
    // 单独使用
    @ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="参数描述")
    登入後複製

    注意,當同時存在@ApiParam和@ApiImplicitParam時,以@ApiImplicitParam的描述為準。

    2.5 @ApiIgnore() 用於類別或方法上,可以不被swagger顯示在頁面上 ,使用較少。

    2.6 回應配置

    • @ApiResponses

    • @ApiResponse

    // 单独配置
    @ApiResponse(code = 400, message = "Invalid user supplied")
    // 组合使用
    @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
    登入後複製

    2.7 @ResponseHeader 回應頭設定

    @ResponseHeader(name="head1",description="response head conf")
    登入後複製

    3.Model中相關swagger註解

    #3.1 @ApiModel 用於類別;表示對類別進行說明,用於參數以實體類別接收。

    @ApiModel(value = "demo", description = "对象描述")
    登入後複製

    一般value和desc可以省略不寫

    3.2 @ApiModelProperty 用於方法,欄位; 表示model屬性的說明或資料操作變更

    @ApiModelProperty(value = "用户id",name = "openid2",dataType = "String", required = true, hidden = true)
    登入後複製
    • value–欄位說明

    • #name–重寫屬性名稱

    • dataType–重寫屬性類型

    • #required–是否必填

    ################# #########example###–舉例說明################hidden###–隱藏############ #一般只對value,required進行標示。 ###

    以上是SpringBoot專案整合Swagger與swagger-bootstrap-ui及常用註解有哪些的詳細內容。更多資訊請關注PHP中文網其他相關文章!

    來源:yisu.com
    本網站聲明
    本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn
    熱門教學
    更多>
    最新下載
    更多>
    網站特效
    網站源碼
    網站素材
    前端模板