swagger-ui增强版knife4j

太过爱你忘了你带给我的痛 2021-09-25 12:12 436阅读 0赞

开源仓库

https://github.com/xiaoymin/swagger-bootstrap-ui

码云

https://gitee.com/xiaoym/knife4j

在线预览

http://knife4j.xiaominfo.com/doc.html

主要功能介绍：

目前主要的模块包括：模块名称说明：knife4j为Java MVC框架集成Swagger的增强解决方案knife4j-admin云端Swagger接口文档注册管理中心,集成gateway网关对任意微服务文档进行组合集成knife4j-extensionchrome浏览器的增强swagger接口文档ui,快速渲染swagger资源knife4j-service为swagger服务的一系列接口服务程序knife4j-frontknife4j-spring-ui的纯前端静态版本,用于集成非Java语言使用swagger-bootstrap-uiknife4j的前身,最后发布版本是1.9.6

pom引用

老版本

<dependency>    
      <groupId>com.github.xiaoymin</groupId>    
      <artifactId>swagger-bootstrap-ui</artifactId>    
      <version>1.9.6</version>
    </dependency>

新版本

<dependency>    
      <groupId>com.github.xiaoymin</groupId>    
      <artifactId>knife4j-spring-ui</artifactId>    
      <version>${ lastVersion}</version>
    </dependency>

spring boot单体项目下

<dependency>    
      <groupId>com.github.xiaoymin</groupId>    
      <artifactId>knife4j-spring-boot-starter</artifactId>    
      <version>${ knife4j.version}</version>
    </dependency>

\*\*

## Spring Cloud微服务架构 ##

\*\*

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter

<dependency>    
      <groupId>com.github.xiaoymin</groupId>    
      <artifactId>knife4j-micro-spring-boot-starter</artifactId>    
      <version>${ knife4j.version}</version>
    </dependency>

在网关聚合文档服务下,可以再把前端的ui资源引入

<dependency>    
       <groupId>com.github.xiaoymin</groupId>    
       <artifactId>knife4j-spring-boot-starter</artifactId>    
       <version>${ knife4j.version}</version>
    </dependency>

## **示例** ##

pom文件

<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.9</version>
    </dependency>

@Configuration
    @EnableSwagger2WebMvc
    public class Knife4jConfiguration {
    
        @Bean(value = "defaultApi2")
        public Docket defaultApi2() {
            Docket docket=new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(new ApiInfoBuilder()
                            .title("API文档")
                            .description("API文档")
                            .termsOfServiceUrl("http://www.xx.com/")
                            .contact("xx@qq.com")
                            .version("1.0")
                            .build())
                    //分组名称
                    .groupName("2.X版本")
                    .select()
                    //这里指定Controller扫描包路径
                    .apis(RequestHandlerSelectors.basePackage("com.*.controller"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
    }

控制器

@Api(tags = "首页模块")    //模块描述
    @RestController
    public class IndexController {
    
        @ApiImplicitParam(name = "name",value = "姓名",required = true)  //参数描述
        @ApiOperation(value = "接口")    //接口描述
        
        @GetMapping("/aaa")
        public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
            return ResponseEntity.ok("Hi:"+name);
        }
    }

访问接口

http://localhost:8088/doc.html

**api的参数解释**  
tags=“说明该类的作用，参数是个数组，可以填多个。”  
value=“该参数没什么意义，在UI界面上不显示，所以不用配置”  
description = “用户基本信息操作”

**@ApiOperation()**：用于方法，表示一个http请求访问该方法的操作  
参数  
value=“方法的用途和作用”  
notes=“方法的注意事项和备注”  
tags：说明该方法的作用，参数是个数组，可以填多个。  
格式：tags=\{“作用1”,“作用2”\}

**@ApiImplicitParam**：用于方法，表示单独的请求参数  
name=“参数ming”  
value=“参数说明”  
dataType=“数据类型”  
paramType=“query” 表示参数放在哪里  
· header–>请求参数的获取：@RequestHeader(代码中接收注解)  
· query–>请求参数的获取：@RequestParam(代码中接收注解)  
· path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)  
· body–>请求参数的获取：@RequestBody(代码中接收注解)  
· form（不常用）  
defaultValue=“参数的默认值”  
required=“true” 表示参数是否必须传

**@ApiImplicitParams**：用在请求的方法上，包含多@ApiImplicitParam  
一般写成如下  
@ApiImplicitParams(\{  
@ApiImplicitParam(),  
@ApiImplicitParam()  
\})

**@ApiModel()**：用于响应实体类上，用于说明实体作用  
description=“描述实体的作用”

**@ApiModelProperty**：用在属性上，描述实体类的属性  
value=“用户名” 描述参数的意义  
name=“name” 参数的变量名  
required=true 参数是否必选

**@ApiParam()**：用于方法，参数，字段说明 表示对参数的要求和说明  
name=“参数名称”  
value=“参数的简要说明”  
defaultValue=“参数默认值”  
required=“true” 表示属性是否必填，默认为false

**@ApiResponses**：用于请求的方法上，根据响应码表示不同响应  
　　一个@ApiResponses包含多个@ApiResponse  
@ApiResponse：用在请求的方法上，表示不同的响应  
参数：  
code=“404” 表示响应码(int型)，可自定义  
message=“状态码对应的响应信息”

**@ApiIgnore()**：用于类或者方法上，不被显示在页面上  
@Profile(\{“dev”, “test”\})：用于配置类上，表示只对开发和测试环境有用

**6 范例**

@ApiOperation("获取活动详细信息")
    @ApiImplicitParams({
    　　@ApiImplicitParam(name = "Authentication", value = "令牌", paramType = "header", dataTypeClass = String.class, required = true),
    　　@ApiImplicitParam(name = "uId", value = "活动ID", paramType = "query", dataTypeClass = String.class, required = true)
    })