Springboot整合Swagger2和Swagger3全過程

更新時間：2024年07月13日 10:45:31 作者：花果水蓮

這篇文章主要介紹了Springboot整合Swagger2和Swagger3全過程,具有很好的參考價(jià)值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教

一、Swagger2的作用

手寫Api文檔的幾個痛點(diǎn)：

文檔需要更新的時候，需要再次發(fā)送一份給前端，也就是文檔更新交流不及時。
接口返回結(jié)果不明確
不能直接在線測試接口，通常需要使用工具，比如postman
接口文檔太多，不好管理

Swagger也就是為了解決這個問題，當(dāng)然也不能說Swagger就一定是完美的，當(dāng)然也有缺點(diǎn)，最明顯的就是代碼移入性比較強(qiáng)。

二、pom依賴:springfox-swagger2、springfox-swagger-ui

<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${swagger2.version}</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>${swagger2.version}</version>
</dependency>

三、Swagger2配置類

@Configuration
@EnableSwagger2 //開啟Swagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("在線教育API文檔")
                .description("本文檔描述了在線教育微服務(wù)接口定義")
                .version("0.0.1-SNAPSHOT")
                .contact(new Contact("java","http://atguigu.com","123456@qq.com"))
                .build();
    }
}

有這兩步就已經(jīng)完成swagger的基本功能，可以訪問http://localhost:{port}/swagger-ui.html，來實(shí)現(xiàn)調(diào)用controller中的接口。如

但實(shí)際上，我們依然可以給controller的類、接口、接口入?yún)⑻砑幼⒔猓?以實(shí)現(xiàn)功能說明的作用。

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數(shù)描述
@ApiModel：用對象來接收參數(shù)
@ApiProperty：用對象接收參數(shù)時，描述對象的一個字段
@ApiResponse：HTTP響應(yīng)其中1個描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發(fā)生錯誤返回的信息
@ApiImplicitParam：一個請求參數(shù)
@ApiImplicitParams：多個請求參數(shù)

四、Controller類添加Swagger的注解

@Api(description = "講師管理") //修飾整個類，描述Controller的作用
@RestController
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    @Autowired
    private EduTeacherService eduTeacherService;

    @ApiOperation("查找全部功能")
    @GetMapping("/findall")
    public List<EduTeacher> findAll(){
        List<EduTeacher> list = eduTeacherService.list();
        return list;
    }

    @ApiOperation("邏輯刪除功能")
    @DeleteMapping("{id}") //{id}表示id值通過路徑傳遞
    public void removeById(@PathVariable("id") String id){
        eduTeacherService.removeById(id);
    }
}

再次訪問Swagger-ui，效果如下

五、整合Swagger3配置類

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //PathSelectors.regex("/error.*")選擇器，negate()表示取反
                .paths(PathSelectors.regex("/error.*").negate())
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("在線教育API文檔")
                .description("本文檔描述了在線教育微服務(wù)接口定義")
                .version("1.0-SNAPSHOT")
                .build();
    }
}