Swagger使用和註釋介紹

時間  2019-11-24
標籤 swagger 使用 註釋 介紹 简体版
原文   原文鏈接

介紹

什麼是Swagger

Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。html

做用前端

  • 接口文檔在線自動生成
  • 功能測試

Swagger是一組開源項目，其中主要要項目以下：java

  • Swagger-tools:提供各類與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。node

  • Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。git

  • Swagger-js: 用於JavaScript的Swagger實現。github

  • Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。web

  • Swagger-ui：一個無依賴的HTML、JS和CSS集合，能夠爲Swagger兼容API動態生成優雅文檔。spring

  • Swagger-codegen：一個模板驅動引擎，經過分析用戶Swagger資源聲明以各類語言生成客戶端代碼。express

在Spring使用Swagger

在Spring中集成Swagger會使用到springfox-swagger，它對Spring和Swagger的使用進行了整合json

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

使用

Spring中配置Swagger

/** * Swagger2配置類 * 在與spring boot集成時，放在與Application.java同級的目錄下。 * 或者經過 @Import 導入配置 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /** * 建立API應用 * apiInfo() 增長API相關信息 * 經過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展示， * 本例採用指定掃描的包路徑來定義指定要創建API的目錄。 * @return */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.turbo.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /** * 建立該API的基本信息（這些基本信息會展示在文檔頁面中） * 訪問地址：http://項目實際地址/swagger-ui.html * @return */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("")
                .termsOfServiceUrl("")
                .contact("zou", "", "zouxq412@foxmail.com")
                .version("1.0")
                .build();
    }
}
複製代碼

API註解

@Api

用在類上，該註解將一個Controller（Class）標註爲一個swagger資源（API）。在默認狀況下，Swagger-Core只會掃描解析具備@Api註解的類，而會自動忽略其餘類別資源（JAX-RS endpoints，Servlets等等）的註解。該註解包含如下幾個重要屬性

  • tags API分組標籤。具備相同標籤的API將會被歸併在一組內展現。
  • value 若是tags沒有定義，value將做爲Api的tags使用
  • description API的詳細描述，在1.5.X版本以後再也不使用，但實際發如今2.0.0版本中仍然可使用

@ApiOperation

在指定的（路由）路徑上，對一個操做或HTTP方法進行描述。具備相同路徑的不一樣操做會被歸組爲同一個操做對象。不一樣的HTTP請求方法及路徑組合構成一個惟一操做。此註解的屬性有：

  • value 對操做的簡單說明，長度爲120個字母，60個漢字。
  • notes 對操做的詳細說明。
  • httpMethod HTTP請求的動做名，可選值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
  • code 默認爲200，有效值必須符合標準的HTTP Status Code Definitions。

@ApiImplicitParams

用在方法上，註解ApiImplicitParam的容器類，以數組方式存儲。

@ApiImplicitParam

對API的單一參數進行註解。雖然註解@ApiParam同JAX-RS參數相綁定，但這個@ApiImplicitParam註解能夠以統一的方式定義參數列表，也是在Servelet及非JAX-RS環境下，惟一的方式參數定義方式。注意這個註解@ApiImplicitParam必須被包含在註解@ApiImplicitParams以內。能夠設置如下重要參數屬性：

  • name 參數名稱
  • value 參數的簡短描述
  • required 是否爲必傳參數
  • dataType 參數類型，能夠爲類名，也能夠爲基本類型（String，int、boolean等）
  • paramType 參數的傳入（請求）類型，可選的值有path, query, body, header or form。

@ApiParam

增長對參數的元信息說明。這個註解只能被使用在JAX-RS 1.x/2.x的綜合環境下。其主要的屬性有

  • required 是否爲必傳參數，默認爲false
  • value 參數簡短說明

@ApiResponses

註解@ApiResponse的包裝類，數組結構。即便須要使用一個@ApiResponse註解，也須要將@ApiResponse註解包含在註解@ApiResponses內。

@ApiResponse

描述一個操做可能的返回結果。當REST API請求發生時，這個註解可用於描述全部可能的成功與錯誤碼。能夠用，也能夠不用這個註解去描述操做的返回類型，但成功操做的返回類型必須在@ApiOperation中定義。若是API具備不一樣的返回類型，那麼須要分別定義返回值，並將返回類型進行關聯。但Swagger不支持同一返回碼，多種返回類型的註解。注意：這個註解必須被包含在@ApiResponses註解中。

  • code HTTP請求返回碼。有效值必須符合標準的HTTP Status Code Definitions。
  • message 更加易於理解的文本消息
  • response 返回類型信息，必須使用徹底限定類名，好比「com.xyz.cc.Person.class」。
  • responseContainer 若是返回類型爲容器類型，能夠設置相應的值。有效值爲 "List", "Set" or "Map"，其餘任何無效的值都會被忽略。

Model註解

對於Model的註解，Swagger提供了兩個：@ApiModel及@ApiModelProperty，分別用以描述Model及Model內的屬性。

@ApiModel

描述一個Model的信息（通常用在請求參數沒法使用@ApiImplicitParam註解進行描述的時候）

提供對Swagger model額外信息的描述。在標註@ApiOperation註解的操做內，全部的類將自動被內省（introspected），但利用這個註解能夠作一些更加詳細的model結構說明。主要屬性有：

  • value model的別名，默認爲類名
  • description model的詳細描述

@ApiModelProperty

描述一個model的屬性

對model屬性的註解，主要的屬性值有：

  • value 屬性簡短描述
  • example 屬性的示例值
  • required 是否爲必須值

註解示例

Api 示例

@AllArgsConstructor
@RestController
@RequestMapping("/api/category")
@Api(value = "/category", tags = "組件分類")
public class BizCategoryController {

    private IBizCategoryService bizCategoryService;

    @GetMapping("/list")
    @ApiOperation(value = "列表", notes = "分頁列表")
    public R<PageModel<BizCategory>> list(PageQuery pageQuery,
                                          @RequestParam @ApiParam("組件分類名稱") String name) {
        IPage<BizCategory> page = bizCategoryService.page(pageQuery.loadPage(),
                new LambdaQueryWrapper<BizCategory>().like(BizCategory::getName, name));
        return R.success(page);
    }

    @GetMapping("/list/all")
    @ApiOperation(value = "查詢全部", notes = "分頁列表")
    public R<List<BizCategory>> listAll() {
        List<BizCategory> categories = bizCategoryService.list();
        return R.success(categories);
    }

    @GetMapping("/{categoryId}")
    @ApiOperation(value = "詳情", notes = "組件分類詳情")
    public R<BizCategory> detail(@PathVariable @ApiParam("分類Id") Long categoryId) {
        BizCategory category = bizCategoryService.getById(categoryId);
        return R.success(category);
    }

    @PostMapping("/save")
    @ApiOperation(value = "保存", notes = "新增或修改")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "form", name = "categoryId", value = "組件id（修改時爲必填）"),
            @ApiImplicitParam(paramType = "form", name = "name", value = "組件分類名稱", required = true)
    })
    public R<BizCategory> save(Long categoryId, String name) {
        BizCategory category = new BizCategory();
        category.setId(categoryId);
        category.setName(name);
        bizCategoryService.saveOrUpdate(category);
        return R.success(category);
    }

    @DeleteMapping("/{categoryId}")
    @ApiOperation(value = "刪除", notes = "刪除")
    public R delete(@PathVariable @ApiParam("分類Id") Long categoryId) {
        bizCategoryService.delete(categoryId);
        return R.success();
    }
}
複製代碼

ApiModel 示例

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="BizComponent對象", description="組件")
public class BizComponent implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    @ApiModelProperty(value = "分類")
    private Long categoryId;

    @ApiModelProperty(value = "組件名稱")
    private String name;

    @ApiModelProperty(value = "組件描述")
    private String description;

    @ApiModelProperty(value = "日期字段")
    private LocalDateTime componentTime;

    @ApiModelProperty(value = "建立時間")
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @ApiModelProperty(value = "修改時間")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime modifiedTime;
}
複製代碼

swagger-ui界面

swagger生成的api文檔信息接口爲/v2/api-docs，不過咱們可使用ui界面更加清晰的查看文檔說明，而且還可以在線調試

springfox-swagger-ui

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.swagger.version}</version>
</dependency>
複製代碼

若是是使用springfox-swagger-ui，啓動項目後的api文檔訪問路徑是 /swagger-ui.html

swagger-bootstrap-ui

swagger-bootstrap-ui是springfox-swagger的加強UI實現，我我的更推薦使用這個ui，api文檔結構更加清晰，在線調試也很方便

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>${swagger.bootstrap.ui.version}</version>
</dependency>
複製代碼

訪問的url爲 /doc.html

Swagger分組

Swagger的分組接口是經過後端配置不一樣的掃描包，將後端的接口，按配置的掃描包基礎屬性響應給前端

後端java的配置以下，指定分組名和各自要掃描的包

@Bean(value = "defaultApi")
public Docket defaultApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("默認接口")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
        .paths(PathSelectors.any())
        .build();
}
@Bean(value = "groupApi")
public Docket groupRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(groupApiInfo())
        .groupName("分組接口")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.group"))
        .paths(PathSelectors.any())
        .build();
}
複製代碼

分組信息的接口爲 /swagger-resources

[
    {
        "name": "分組接口",
        "url": "/v2/api-docs?group=分組接口",
        "swaggerVersion": "2.0",
        "location": "/v2/api-docs?group=分組接口"
    },{
        "name": "默認接口",
        "url": "/v2/api-docs?group=默認接口",
        "swaggerVersion": "2.0",
        "location": "/v2/api-docs?group=默認接口"
    }
]
複製代碼

在swagger-ui中也能夠經過分組來查看api文檔

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程