SpringBoot集成Swagger

目錄：

    什麼是Swagger
    Swagger的優點
    Swagger的作用
    SpringBoot集成Swagger
    Swagger的使用
    總結
    分享與交流

什麼是Swagger

    Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試軟件，隨着前後端分離的思想越來越多的被互聯網公司採用，Swagger也越來越受歡迎。

Swagger的優點

   • Swagger可以整合到代碼中，在開發時通過註解，編寫註釋，自動生成API文檔。
   • 將前端後臺分開，不會有過分的依賴。
   • 界面清晰，無論是editor的實時展示還是ui的展示都十分人性化，如果自己僅僅用markdown來編寫，又要糾結該如何展現，十分痛苦。
   • 支持Json和yaml來編寫API文檔，並且支持導出爲json、yaml、markdown等格式。
   •直接運行，可在線測試API接口。

Swagger的作用

   1.接口的文檔在線自動生成
   2.功能測試，類似於postman

SpringBoot集成Swagger

（1）創建SpringBoot工程，可以參考SpringBoot—搭建boot框架的三種方式
（2）引入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>

   這個時候Swagger基本上就已經配置的差不多了，後面是一些Swagger的使用。

Swagger的使用

（1）創建config包，在包下創建SwaggerConfig.java

@Configuration  //等價於@Component
@EnableSwagger2
public class SwaggerConfig {

}

啓動項目，訪問http://localhost:8080/swagger-ui.html

（2）修改文檔信息
SwaggerConfig.java

@Configuration //等價於@Component
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.lxy.spring_boot1.controller"))@Configuration //等價於@Component
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)  //不寫默認爲true，表示開啓Swagger,false表示關閉Swagger
                .select()
                //RequestHandlerSelectors.basePackage()掃描指定包下接口
                //RequestHandlerSelectors.none()什麼也不掃
                //RequestHandlerSelectors.any()都掃
                .apis(RequestHandlerSelectors.basePackage("cn.lxy.spring_boot1.controller"))
                //PathSelectors.none()選擇路徑爲空，什麼接口也掃不到
                //PathSelectors.any()選擇路徑爲所有，所有接口都掃到
                //PathSelectors.ant()選擇指定路徑，指定路徑接口掃到
                //PathSelectors.regex()正則，符合條件的掃到
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Jacob的Swagger文檔")
                .description("Jacob API 網關接口，https://blog.csdn.net/llllxxxxyyyy")
                .termsOfServiceUrl("https://blog.csdn.net/llllxxxxyyyy")
                .version("v1.0.0")
                .build();
    }
}
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Jacob的Swagger文檔")
                .description("Jacob API 網關接口，https://blog.csdn.net/llllxxxxyyyy")
                .termsOfServiceUrl("https://blog.csdn.net/llllxxxxyyyy")
                .version("v1.0.0")
                .build();
    }
}

(3)創建多個組信息

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("Jacob")//設置組名
                .enable(true)  //不寫默認爲true，表示開啓Swagger,false表示關閉Swagger
                .select()
                //RequestHandlerSelectors.basePackage()掃描指定包下接口
                //RequestHandlerSelectors.none()什麼也不掃
                //RequestHandlerSelectors.any()都掃
                .apis(RequestHandlerSelectors.basePackage("cn.lxy.spring_boot1.controller"))
                //PathSelectors.none()選擇路徑爲空，什麼接口也掃不到
                //PathSelectors.any()選擇路徑爲所有，所有接口都掃到
                //PathSelectors.ant()選擇指定路徑，指定路徑接口掃到
                //PathSelectors.regex()正則，符合條件的掃到
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRestApi1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("測試")//設置組名
                .enable(true)  
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.lxy.spring_boot1.controller"))
                .paths(PathSelectors.any())
                .build();
    }

   多個組就創建多個Docket
（4)接口文檔註釋
Model實體類

@Data //自動創建getter，setter，toString等方法
@AllArgsConstructor //自動創建構造函數
@ApiModel("用戶類")
public class User {
    @ApiModelProperty("用戶編號")
    private Integer id;
    @ApiModelProperty("用戶名")
    private String name;
    @ApiModelProperty("用戶年齡")
    private Integer age;
}

接口

@RestController
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/findAll")
    @ApiOperation("查找所有用戶")
    public List<User> findAll(){
        return userRepository.findAll();
    }

    @GetMapping("/findById/{id}")
    @ApiOperation("查找指定用戶")
    public User get(@ApiParam("用戶編號") @PathVariable("id") Integer id){
        return userRepository.findById(id);
    }

    @PostMapping("/add")
    @ApiOperation("添加用戶")
    @ResponseBody
    public int add(@ApiParam("用戶信息")User user){
        return userRepository.add(user);
    }

    @PutMapping("/update")
    @ApiOperation("修改用戶")
    @ResponseBody
    public int update(@ApiParam("用戶信息")User user){
        return userRepository.update(user);
    }

    @DeleteMapping("/deleteById/{id}")
    @ApiOperation("刪除指定用戶")
    public int deleteById(@ApiParam("用戶編號") @PathVariable("id") Integer id){
        return userRepository.deleteById(id);
    }
}

（5）功能測試
點擊Try it out

原數據如下

功能測試

新數據如下

總結

   1.我們可以通過Swagger給一些比較難理解的接口或類進行註釋
   2.接口文檔實時更新
   3.接口文檔可在線測試
   4.多人開發可用多個組，最後再進行整合Swagger
   5.在正式發佈的時候，Swagger一定要記得關閉，一是出於安全考慮，不能將接口文檔暴露給用戶，二是減小服務器壓力

分享與交流

   由於能力有限，博客總結難免有不足，還請大佬們不吝賜教😄