在SpringBoot中Swagger配置及使用

Swagger號稱世界上最流行的Api框架,它是RestFul 風格的Api。文檔在線自動生成工具：Api文檔與API定義同步更新。可以直接運行，能在線測試API接口；支持多種編程語言：（Java、PHP等）。

官網：https://swagger.io/

在項目中使用Swagger需要配置springbox

SpringBoot集成Swagger

1.新建一個springboot的web項目

2.導入swagger相關依賴

                <!--swagger-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>                

3.編寫一個簡單項目工程

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

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

4.創建一個config，新建一個SwaggerConfig配置swagger

@Configuration//配置類，加上就能配置到配置里面
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {
    
}

5.測試swagger是否能使用

swagger測試地址：http://localhost:8080/swagger-ui.html

配置swagger

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration//配置類，加上就能配置到配置里面
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {
    //配置了swaggerDocket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger信息apiInfo
    private ApiInfo apiInfo(){

        //作者信息
        Contact DEFAULT_CONTACT = new Contact("ljj", "https://www.cnblogs.com/jjsir/", "[e-mail]");

        return new ApiInfo(
                "ljj  SwaggerAPI文檔",
                "學海無涯苦作舟",
                "1.0",
                "https://www.cnblogs.com/jjsir/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

swagger配置掃描接口

    //配置了swaggerDocket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //RequestHandlerSelectors配置掃描接口方式
                //.basePackage("com.ljj.controller");指定要掃描的包
                //.any();全部掃描
                //.none();全不掃描
                //.withClassAnnotation(RestController.class);掃描類上的注解，參數是一個注解的反射對象
                //.withMethodAnnotation(GetMapping.class);掃描方法上的注解
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ljj.swagger.controller"))
                //.paths()過濾什么路經
                .paths(PathSelectors.any())
                .build();
    }

在.select()上方配置.enable(false) 可以判斷是否啟動swagger 為false則不啟動。
可以給swagger設置在開發環境中使用，部署環境中不使用

    //配置了swaggerDocket的bean實例
    @Bean
    public Docket docket(Environment environment){
        //設置要顯示的swagger環境
        Profiles profiles = Profiles.of("dev", "test");
        //通過environment.acceptsProfiles 判斷是否處在自己設定環境中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)  //是否啟動swagger   當前是"dev", "test"環境就為true 否則為false則不啟動 
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ljj.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

使用.groupName("swagger學習")  對swagger分組進行自定義命名

配置API文檔的分組

    //分組
    @Bean
    public Docket docket1(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

使用多個@Bean可以swagger分組

實體類配置

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

//@Api (注釋)
@ApiModel(value = "user實體類")
public class User {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;
}

controller

import com.ljj.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController{

    @GetMapping(value = "/helloWord")
    public String helloWord(){
        return "hello word";
    }

    //只要我們接口中返回值存在實體類，他就會被掃描到swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    //Operation接口 不是放類上面的，他是方法
    @ApiOperation("hello控制類")
    @PostMapping("/select")
    public String select(@ApiParam("用戶名") String username){
        return "hello"+username;
    }

    @ApiOperation("Post測試類")
    @PostMapping("/selectUser")
    public User selectUser(User user){
        return user;
    }
}

結束語

我們可以通過swagger把比較難理解的屬性和接口添加注釋，方便和前端對接，而且swagger可以及時更新、在線測試。

注意點：出於安全考慮，和節省內存   正式上線時請關閉swagger！！！

 

來源地址：狂神說  https://www.bilibili.com/video/BV1Y441197Lw?p=4