快捷導(dǎo)航

Java Swagger技術(shù)使用指南

更新時(shí)間：2021年09月30日 14:48:04 作者：四季人06

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來(lái)始終保持同步

Swagger的作用與概念

Swagger官網(wǎng)，點(diǎn)此進(jìn)入
在前后端分離時(shí)代，我們需要實(shí)時(shí)自動(dòng)更新接口信息，和測(cè)試接口，實(shí)現(xiàn)前后端分離式開(kāi)發(fā)，swagger因此產(chǎn)生

在項(xiàng)目中使用swagger

以下以3.0.0依賴為例

 <!--swagger 相關(guān)組件-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>
          <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-boot-starter</artifactId>
           <version>3.0.0</version>
        </dependency>

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
         return "hello";
    }
}

@Configuration
@EnableSwagger2 //開(kāi)啟swagger2
public class SwaggerConfig {

}

然后訪問(wèn)http://localhost:8080/swagger-ui/index.html
你就能看到如下界面，為swagger文檔

在這里插入圖片描述

配置swagger

先來(lái)看看底層的代碼，了解一下

在這里插入圖片描述

ApiInfo 配置

@Configuration
@EnableSwagger2 //開(kāi)啟swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("宋先慧", "https://blog.csdn.net/sxh06", "xianhuisong@yeah.net");
        return new ApiInfo(
                "宋先慧的Api Documentation",
                "學(xué)習(xí)swagger沒(méi)有盡頭",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

swagger配置掃描接口

@Configuration
@EnableSwagger2 //開(kāi)啟swagger2
public class SwaggerConfig {

//    @Bean
//    public Docket docket1(){
//        return new Docket(DocumentationType.SWAGGER_2).groupName("分組二");
//    }
    @Bean
    public Docket docket(Environment environment){


        Profiles profiles=Profiles.of("dev");
        //獲取項(xiàng)目的環(huán)境
         boolean flag=environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("宋先慧")  //分組
                .enable(flag)  //enable 配置是否啟動(dòng)swagger  flase則不能在瀏覽器訪問(wèn)
                .select()
                //RequestHandlerSelectors實(shí)現(xiàn)類  配置掃描方式
                // basePackage指定要掃描的包
                // any()全部
                // none()都不掃描
                //withClassAnnotation()  掃描類上的注解  參數(shù)是一個(gè)注解的反射對(duì)象
                //withMethodAnnotation   掃描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.sxh.swagger.controller"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //過(guò)濾什么路勁  過(guò)濾請(qǐng)求
                //.paths(PathSelectors.ant("/sxh/**"))
                .build();
    }

    //配置swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("宋先慧", "https://blog.csdn.net/sxh06", "xianhuisong@yeah.net");
        return new ApiInfo(
                "宋先慧的Api Documentation",
                "學(xué)習(xí)swagger沒(méi)有盡頭",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

如果我只希望在生成環(huán)境使用swagger,在正式環(huán)境不使用swagger怎么解決？（enable=false|true）

配置api文檔分組

在這里插入圖片描述

多個(gè)分組

配置多個(gè)Docket 實(shí)例即可

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("分組一");
    }

 @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("分組二");
    }`