Spring Boot內建Swagger導入YApi@無界程式設計

接口APi開發現狀

現在開發接口都要在類似YApi上寫文檔，這樣友善不同的團隊之間協作，同步更新接口，提高效率。

但是如果接口很多，你一個個手工在YApi去錄入無疑效率很低。

如果是使用Spring Boot內建Swagger可以直接導入YApi非常友善，不過還有一些需要注意的事項。

1.Spring Boot內建Swagger

添加swagger相關的maven依賴

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

複制

2.添加swagger的配置類

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = { "xxx.controller" })//掃描的包路徑
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .paths(PathSelectors.any()).build();
    }

/**
     * 該套 API 說明，包含作者、簡介、版本、host、服務URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api 說明")//接口标題
                .description("商品清單接口")//接口描述
                .version("v1.0")//版本号
                .contact(new Contact("name", "url", "email"))//聯系人資訊
                .build();
    }
}

複制

或者

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //掃描的包路徑
                .build();
    }

    /**
     * 該套 API 說明，包含作者、簡介、版本、host、服務URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api 說明")
                .contact(new Contact("allen","null","[email protected]"))
                .version("0.1")
                .termsOfServiceUrl("localhost:8080/demo/")
                .description("demo api")
                .build();
    }

}

複制

3.使用Swagger注解

@Api()用于類；

辨別這個類是swagger的資源

tags–表示分組說明标簽

@ApiOperation()用于方法；

表示一個http請求的操作

value用于方法描述

notes用于提示内容

@ApiModel()用于實體類

表示對類進行說明，用于參數用實體類接收

value–表示對象名

description–描述

@ApiModelProperty()用于實體類字段

表示對model屬性的說明或者資料操作更改

value–字段說明

name–重寫屬性名字

dataType–重寫屬性類型

required–是否必填

example–舉例說明

hidden–隐藏

@ApiImplicitParam() 用于 controller 方法

表示單獨的請求參數

name–參數ming

value–參數說明

dataType–資料類型

paramType–參數類型

example–舉例說明

@ApiImplicitParams() 用于 controller 方法，包含多個 @ApiImplicitParam

@ApiIgnore()用于類或者方法上，可以不被swagger顯示在頁面上

說明：簡單的标記隻需要@Api(tags="") 和 @ApiOperation(value="",notes="")

更多參考：https://github.com/swagger-api/swagger-core/wiki/Annotations

4.Java代碼寫上Swagger注解

@Api(tags = "xxx查詢清單Api")
@RestController
@RequestMapping(value = {"/xx/"}, produces = {MediaType.APPLICATION_JSON_VALUE})
public class xxxApiController {


    @GetMapping("/xxx/getAllList")
    */
    @ApiOperation("xxxx-查詢清單")
    @PostMapping(value = {"/xxx/getList", "/front/getCount"}

複制

5.檢視Swagger UI

随着你系統的URL路徑不同而不同，預設在這

http://localhost:8080/swagger-ui.html

如果你有服務的字首xxx-service加上即可

http://localhost:8080/xxx-service/swagger-ui.html

檢視某一個controller下的接口清單：

檢視某個具體接口：

傳回值

至此swagger的任務已經完成。

6.swagger導入YApi

swagger ui顯然看起來還是不友善，目前很多公司都在用YApi做接口的标準文檔管理了。

YAPI裡點資料管理，然後導入swagger的json資料即可。

注意這裡YAPI号稱支援導入swagger的URL，發現不好用，導入不進來。

回到swagger的UI界面

點這個連結，打開複制資料存為xxx.json即可，如果存txt也許會亂碼

導入yapi即可

在Ypai裡看起來是不是清爽很多：

本文由來源 21aspnet，由 system_mush 整理編輯，其版權均為 21aspnet 所有，文章内容系作者個人觀點，不代表 Java架構師必看對觀點贊同或支援。如需轉載，請注明文章來源。