Swagger和knife4j簡單應用

Swagger和knife4j使用

Swagger使用

一、簡介

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務(https://swagger.io/)。 它的主要作用是：

1. 使得前后端分離開發更加方便，有利於團隊協作

2. 接口的文檔在線自動生成，降低后端開發人員編寫接口文檔的負擔

3. 功能測試

   Spring已經將Swagger納入自身的標准，建立了Spring-swagger項目，現在叫Springfox。通過在項目中引入Springfox ，即可非常簡單快捷的使用Swagger。

二、SpringBoot集成Swagger

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

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

   @Bean
   public Docket buildDocket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              .select()
              // 要掃描的API(Controller)基礎包
              .apis(RequestHandlerSelectors.basePackage("com.stone"))
              .paths(PathSelectors.any())
              .build();
   }

   private ApiInfo buildApiInfo() {
      return new ApiInfoBuilder()
              .title("stoneAPI文檔")
              .description("平台管理服務api")
              .contact("stone")
              .version("1.0.0").build();
   }
}

三、Swagger常用注解

在Java類中添加Swagger的注解即可生成Swagger接口文檔，常用Swagger注解如下：

@Api：修飾整個類，描述Controller的作用 @ApiOperation：描述一個類的一個方法，或者說一個接口 @ApiParam：單個參數的描述信息

@ApiModel：用對象來接收參數

@ApiModelProperty：用對象接收參數時，描述對象的一個字段

@ApiResponse：HTTP響應其中1個描述

@ApiResponses：HTTP響應整體描述

@ApiIgnore：使用該注解忽略這個API

@ApiError ：發生錯誤返回的信息

@ApiImplicitParam：一個請求參數

@ApiImplicitParams：多個請求參數的描述信息

@ApiImplicitParam屬性：

屬性	取值	作用
paramType		查詢參數類型
	path	以地址的形式提交數據
	query	直接跟參數完成自動映射賦值
	body	以流的形式提交 僅支持POST
	header	參數在request headers 里邊提交
	form	以form表單的形式提交 僅支持POST
dataType		參數的數據類型 只作為標志說明，並沒有實際驗證
	Long
	String
name		接收參數名
value		接收參數的意義描述
required		參數是否必填
	true	必填
	false	非必填
defaultValue		默認值

四、測試

通過路徑/swagger-ui.html訪問

Knife4j使用

一、簡介

knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一樣小巧,輕量,並且功能強悍!

gitee地址：https://gitee.com/xiaoym/knife4j

官方文檔：https://doc.xiaominfo.com/

效果演示：http://knife4j.xiaominfo.com/doc.html

二、springboot集成

<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
    //高版本可能會有沖突
</dependency>

@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Configuration {

      @Bean
   public Docket buildDocket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              .select()
              // 要掃描的API(Controller)基礎包
              .apis(RequestHandlerSelectors.basePackage("com.stone"))
              .paths(PathSelectors.any())
              .build();
   }

   private ApiInfo buildApiInfo() {
      return new ApiInfoBuilder()
              .title("stoneAPI文檔")
              .description("平台管理服務api")
              .contact("stone")
              .version("1.0.0").build();
   }
}

三、測試

通過路徑/doc.html訪問