swagger注解使用

草莓软糖将军
572 阅读4分钟

Swagger2

官网文档:API Documentation & Design Tools for Teams | Swagger

注:如果springboot版本过高，即2.6.x以上，需要额外配置才能启动成功

下面的依赖适合于2.6.x版本以下

基本使用

依赖导入

		
		<!--swagger2 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
		<!--官方 swaggerui依赖-->
		<dependency>
    		<groupId>io.springfox</groupId>
   	 		<artifactId>springfox-swagger-ui</artifactId>
    		<version>2.7.0</version>
		</dependency>
        <!--swagger第三方ui依赖-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

开启注解

在swagger2中是通过@EnableSwagger2开启swagger使用

启动成功后可访问如下路径

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

package com.example.portablefortheelderlybackground;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class PortableForTheElderlyBackgroundApplication {

    public static void main(String[] args) {
        SpringApplication.run(PortableForTheElderlyBackgroundApplication.class, args);
    }

}

swagger配置类

用于配置文档信息

package com.reggie.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
//        创建docket对象,其中DocumentationType.SWAGGER_2是swagger2的配置
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
//        构建者模式
        ApiInfo apiInfo = new ApiInfoBuilder().title("Reggie外卖").//设置标题
                contact(new Contact("唐志峰", "https://tzfcw.top", "2166327292@qq.com"))//设置联系方式
                .description("reggie外卖是黑马程序员的项目")//设置描述信息
                .version("1.0")//设置版本号
                .build();//构建
        docket.apiInfo(apiInfo);
//        设置扫描包
        docket=docket.select().apis(RequestHandlerSelectors.basePackage("com.reggie.controller")).build();//重新构建
        return docket;
    }
}

自定义注解

自己编写注解，扩展功能java

package com.reggie.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
//        创建docket对象,其中DocumentationType.SWAGGER_2是swagger2的配置
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
//        设置扫描包,以及对添加了自定义注解的方法或类做规则
      docket=docket.select().apis(Predicates.and(RequestHandlerSelectors.basePackage("com.reggie.controller"),
                Predicates.not(RequestHandlerSelectors.withClassAnnotation(ApiHideController.class)))).build();//not是取反,这里取反就是不显示controller
        return docket;
    }
}

设置路径范围

通过Docket对象的select中的path()设置，docket中的规则设置都是通过Predicates实现，内部有多种规则定义。

docket.select().paths(Predicates.or(
                PathSelectors.regex("/user/.*") //PathSelectors是路径选择
        )).build()

@Api

用在控制类上,通过tags给控制类起别名

@Api(tags = {"用户登录控制器"})

@ApiOperation

用在控制器的具体方法上,通过value添加方法作用描述,note作具体描述

	@ApiOperation(value = "用户邮箱注册", notes = "目前只支持邮箱注册")
    public void SaveCreateUser(@RequestParam("email") String email, HttpSession session) {
        
    }

@ApiParam

用在方法参数上，字段和方法上，其中用在方法参数上name是必须填的，用于参数的别名，其中还是value是对参数的描述

@RequestParam("email") @ApiParam(name = "用户邮箱", value = "用户注册时填写的合法邮箱") String email

@ApiIgnore

可用于类，方法，参数上，添加该注解的类或者方法不会被展示到帮助文档上，会被忽略

@ApiImplicitParams

用于描述唯一的参数名(用于方法上),对于单个的参数可以直接使用@ApiImplicitParam,其中含有的常用参数有

  • name，用于唯一参数的别名
  • value是参数的描述
  • paramType是携带参数的类型，有header,form,query,body
  • dataType是参数的数据类型
@ApiImplicitParams(
            value = {
                    @ApiImplicitParam(name = "email", value = "用户邮箱", paramType = "携带参数的类型", dataType = "String")
            }
    )

@ApiModel

其中@ApiModel是描述实体类的注解，当实体类被当作返回值类型返回时，才起作用，

其中@ApiModelProperty是描述字段信息的注解,包含如下常用参数

  • name,字段属性名
  • value,字段属性描述
  • dataType,字段数据类型
  • example,参数示例
  • required,参数是否是必须的
	package com.reggie.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * 用户信息
 */
@Data
@ApiModel(value = "用户类", description = "更详细的描述")
public class user implements Serializable {

    private static final long serialVersionUID = 1L;
    @ApiModelProperty(name = "主键(id)", value = "用户id", dataType = "Long", example = "2343259347", required = true)
    private Long id;
//.........
}

Knife4j-UI

Knife4j文档请求异常 | Knife4j (xiaominfo.com) 访问地址:http://ip:port/doc.html

依赖导入

下面的依赖是能够保证运行,如果使用swagger3,则knife4j的依赖也需要进行升级

整合swagger2
        <!--swagger2 依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--官方 swaggerui依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--   knif4j 依赖    -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>
整合swagger3
<!--   knif4j 依赖    -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<!--   swagger3 依赖    -->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
</dependency>

swagger的配置

在启动类加上@EnableKnife4j注解,

@EnableKnife4j
@SpringBootApplication
public class EamApplication {
    //.....
}

同时将swagger配置中的文档类型改成OAS_30,同时添加@EnableOpenApi注解

Docket docket = new Docket(DocumentationType.OAS_30);

总结:

swagger3 VS swagger2 swagger3 和swagger2 的区别主要体现在以下方面：

启动 Swagger 的注解不同：swagger3使用的是 @EnableOpenApi，而swagger2是 @EnableSwagger2； Docket（文档摘要信息）的文件类型配置不同：swagger3配置的是 OAS_3，而swagger2是 SWAGGER_2

Knife4j

快速开始 | Knife4j (xiaominfo.com),跟swagger一样，用于api文档

Gitee:knife4j: Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案 (gitee.com)

avatar
文章
阅读
粉丝