Swagger3.x-2.x

最新推荐文章于 2024-09-30 16:50:06 发布
最新推荐文章于 2024-09-30 16:50:06 发布
阅读量695 收藏 2
点赞数 1
分类专栏： 常用开发工具之Java
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_36259143/article/details/115600685
版权

API管理系统介绍

前后端都分离了，该搞个好用的API管理系统了！

参考文献：https://mp.weixin.qq.com/s/Ahs6fnIfFVVPOn3NZpIsNA

Swagger： https://swagger.io/

YApi：http://yapi.demo.qunar.com/

eolinker：https://www.eolinker.com/

易文档：https://easydoc.xyz/

Swagger 3.X

OpenApi规范

接口文档

  • 谁产生：接口开发人员，后端工程师
  • 谁维护：接口开发人员，后端工程师
  • 谁使用：前端同学、测试同学、产品经理

接口存在的问题：

  • 接口文档不存在，靠抓包获取
  • 接口更换后不及时更新
  • 接口文档写错，注解写错
  • 自动生成文档工具在跨语言不兼容

OpenApi规范：声明了用于文档的规范的版本

  • 地址：https://github.com/OAI/OpenAPI-Specification
OpenAPI规范经过Reverb Technologies和SmartBear等公司多年的发展，OpenAPI计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。

规范是一种与语言无关的格式，用于描述RESTful Web服务，应用程序可以解释生成的文件，这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

开放API规范（OAS）是一种无需编写实际API代码就可以记录API的方法。 这是一种开放源代码格式，可以用来描述API。 在此过程中，我们可以使用JSON或YAML格式。

OpenAPI文档有三个必需的部分或对象，也可以增加其他模块：

  1. openapi - OpenAPI规范版本的语义版本号
  2. info - 有关API的元数据
  3. paths - API的可用路径和操作

Api文档管理工具对比

ApiDoc

  • 地址：https://apidocjs.com/

  • github: https://github.com/apidoc/apidoc

  • 简介：源代码中的注释直接自动生成api接口文档的工具

  • 优点：不入侵代码、支持跨语言使用、界面友好简洁

  • 缺点：依赖环境 node/npm

  • 示例：在代码里面增加注释使用

        /**
     * @apiGroup Product
     * @api {GET} /product/{id}  查询一个产品
     * @apiDescription 接口描述xxx
     * @apiParam {String} id 产品id(必填*)
     * @apiSuccessExample SuccessExample
     * HTTP/1.1 200
     * {
     * id: 'xxx',
     * name: 'xxx',
     * desc: 'xxxx'
     * }
     * @apiErrorExample ErrorExample
     */
    @GetMapping("/{id}")
    public Product detail(@PathVariable String id){
        return JsonData.buildSuccess();
    }

Swagger 丝袜哥

  • 地址：https://swagger.io/tools/swagger-ui/

  • 简介：在java代码里面增加注解生成接口文档

  • 优点：支持SpringBoot等主流Java框架、对java代码友好、界面简洁、国内比较活跃,主要是spring社区带动、功能比较多

  • 缺点：对跨语言支持不友好（可以和knife4j整合解决这个问题）、代码需要引入相关依赖包和配置、文档相对缺少

  • 示例：在代码里面增加注解

    RestController
@RequestMapping("/api/v1/user")
@Api(tags = "用户模块",value = "用户UserController")
public class UserController {

    @Autowired
    private BannerService bannerService;

    @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){
        List<BannerDO> list = bannerService.list();
        return JsonData.buildSuccess(list);
    }
}

Swagger3快速入门

springfox3.0 已经支持swagger3了，之前SpringFox未支持 OpenAPI3 标准使用的是springdoc-openapi-ui依赖

1、创建SpringBoot项目，并确保项目能够正确运行。

2、导入相关maven依赖（对比Swagger2，Swagger3只需要导入一个依赖即可）：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

3、Swagger3配置类

/**
 * @EnableOpenApi：开启Swagger3的注解。与Swagger2启动注解不同@EnableSwagger2
 * @EnableOpenApi 不配置也可以
 */
@EnableOpenApi
@Configuration
public class Swagger3Config {

}

4、访问swagger3-ui地址：http://localhost:8080/swagger-ui/index.html

Swagger3配置详解

application.properties配置文件

# 项目名称
spring.application.name=Swagger3.x api

########### 自定义swagger配置 ###########
# 是否开启swagger，开发环境打开，线上关闭
# 项目名称：enable
# 项目版本信息：application-version
# 项目描述信息：application-description
swagger.enable=true
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
swagger.application-description=Swagger3.x api info

Swagger配置类

/**
 * @EnableOpenApi：开启Swagger3的注解。与Swagger2启动注解不同@EnableSwagger2
 * 默认不配置也可以
 */
@EnableOpenApi
@Configuration
public class Swagger3Config {
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里成变量
     */
    @Value("${swagger.enable}")
    private Boolean enable;
    /**
     * 项目应用名
     */
    @Value("${swagger.application-name}")
    private String applicationName;
    /**
     * 项目版本信息
     */
    @Value("${swagger.application-version}")
    private String applicationVersion;
    /**
     * 项目描述信息
     */
    @Value("${swagger.application-description}")
    private String applicationDescription;

    /**
     * 配置了Swagger的Docket的bean实例：Swagger3 需要配置成 DocumentationType.OAS_30
     *  enable()：是否启动Swagger，如果为False，则Swagger不能在浏览器中访问
     *  apiInfo()：配置api文档元信息
     *  select()：选择哪些接口作为swagger的doc发布，一般和apis()一起使用
     *  apis(RequestHandlerSelectors.XXX)：配置要扫描的方式
     *      RequestHandlerSelectors.basePackage()：指定要扫描的包
     *      RequestHandlerSelectors.any()：扫描全部
     *      RequestHandlerSelectors.none()：不扫描
     *      RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，参数是注解的反射对象
     *      RequestHandlerSelectors.withMethodAnnotation()：扫描方法上的注解，参数是注解的反射对象
     *      例如：RequestHandlerSelectors.withClassAnnotation(ApiOperation.class)
     *  paths()：过滤什么路径，一般跟在select()之后，根据请求路径定义当前Docket需要包含控制器的哪些方法。
     *      PathSelectors.none()：不扫描
     *      PathSelectors.any()：扫描所有请求路径
     *      PathSelectors.ant("/*")：匹配Ant样式的路径模式
     *      PathSelectors.regex("/cat/.*")：匹配正则指定的正则表达式路径
     *  pathMapping()：默认请求都是以 / 根路径开始.如果我们的应用不是部署在根路径，
     *                 比如以/platform 部署，则可以通过一下方式设置请求的统一前缀。最终调用接口后会和paths拼接在一起.
     *                 如接口为：/v1/api/list，那么swagger-ui页面则显示/platform/v1/api/list
     *
     *  build：工厂模式
     *  注意：Docket.select().xxx.build()必须一起使用
     *        select() 返回的是一个ApiSelectorBuilder对象，而我们需要的却是Docket对象，
     *        因此，ApiSelectorBuilder类中提供了一个方法 --> build() 方法返回的是一个Docket对象。
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/");
    }

    /**
     * ApiInfo：主要返回接口和接口创建者的信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("lsx", "https://www.cnblogs.com/liusuixing/", "8629303@qq.com"))
                .version(applicationVersion)
                .build();
    }
}

分组配置：（其他配置都是一样的）

@Bean
public Docket docketA(){
    return new Docket(DocumentationType.OAS_30).groupName("A");
}

@Bean
public Docket docketB(){
    return new Docket(DocumentationType.OAS_30).groupName("B");
}

解决访问swaggerUI接口文档显示basic-error-controler问题：

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        .pathMapping("/")
        .select() // 选择那些路径和api会生成document
        .apis(RequestHandlerSelectors.any())// 对所有api进行监控
        // 不显示错误的接口地址
        .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
        .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
        .build();
}

Swagger3常用注解

注解作用
@Api用在Controller类上，对所标注的类进行描述说明。
@ApiOperation用在COntroller类中的方法上，对所标注的方法进行描述说明。
@ApiImplicitParams、@ApiImplicitParam方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
@ApiParam用于 Controller 中方法的参数说明。
@ApiResponse、@ApiResponses方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明
@ApiModel、@ApiModelProperty用在实体类和属性上，对实体类和属性进行说明
@ApiIgnore用在类、方法，参数中用来屏蔽某接口或参数，使其不在页面上显示
@Api：用在请求的类上，表示对类的说明（不配置默认是按类名驼峰变下划线显示）
    value：表示说明
    tags：也是说明，可以替代或者覆盖value，tags如果有多个值，会生成多个list
    description：对api资源的描述
    basePath：基本路径
    position：如果配置多个Api 想改变显示的顺序位置
    produces：如 “application/json, application/xml”
    consumes：如 “application/json, application/xml”
    protocols：协议类型，如: http, https, ws, wss.
    authorizations：高级特性认证时配置
    hidden：配置为true ，将在文档中隐藏

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value：用于方法描述
    tags：可以重新分组（视情况而用）
    notes：用于提示内容

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · div（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
    name：参数名
    value：参数说明
    required：是否必填
    defaultValue：默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一个@ApiResponse表示一种响应信息
        responseCode：字符串，例如"400"
        description：信息，例如"请求参数没填好"

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    value：自定义类的名称
    description：为类添加长文本描述信息
    
@ApiModelProperty：用在属性上，描述响应类的属性
    value：定义参数描述信息
    name：定义参数名称
    required：是否必填

实例：

package com.example.swagger.controller;

import com.example.swagger.model.ApiResult;
import com.example.swagger.model.User;
import io.swagger.annotations.*;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

@Api(tags = "用户模块" ,description = "User module")
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 参数形式一：@ApiImplicitParams、@ApiImplicitParam
     */
    @ApiOperation(value = "新增用户A", notes = "添加新的用户", tags = "用户模块",httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "email", value = "邮箱", required = true, dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "保存成功"),
            @ApiResponse(responseCode = "400", description = "保存失败")
    })
    @PostMapping("/swagger3AnnotationA")
    public ApiResult swagger3AnnotationA(@RequestParam("name") String name,
                                         @RequestParam("age") Integer age,
                                         @RequestParam("email") String email){
        return ApiResult.builder().code(200).message("返回成功").build();
    }

    /**
     * 参数形式二：@ApiParam
     */
    @ApiOperation(value = "新增用户B", notes = "添加新的用户", tags = "用户模块",httpMethod = "POST")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "保存成功"),
            @ApiResponse(responseCode = "400", description = "保存失败")
    })
    @PostMapping("/swagger3AnnotationB")
    public ApiResult swagger3AnnotationB(
            @ApiParam(name = "name", value = "用户名") @RequestParam("name") String name,
            @ApiParam(name = "age", value = "年龄")@RequestParam("age") String age,
            @ApiParam(name = "email", value = "邮箱")@RequestParam("email") String email){
        return ApiResult.builder().code(200).message("返回成功").build();
    }

    /**
     * 参数形式三：@ApiModel、@ApiModelProperty
     */
    @ApiOperation(value = "新增用户C", notes = "添加新的用户", tags = "用户模块",httpMethod = "POST")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "保存成功"),
            @ApiResponse(responseCode = "400", description = "保存失败")
    })
    @PostMapping("/swagger3AnnotationC")
    public ApiResult swagger3AnnotationC(@RequestBody User user){
        return ApiResult.builder().code(200).message("返回成功").data(user).build();
    }
}

两个model类：

@Data
@Builder
@ApiModel(description= "返回响应数据")
public class ApiResult {
    @ApiModelProperty(value = "是否成功",required=true)
    private boolean success = true;
    @ApiModelProperty(value = "http状态码")
    private Integer code;
    @ApiModelProperty(value = "提示信息")
    private String message;
    @ApiModelProperty(value = "数据")
    private Object data;
}

@Data
@ApiModel(description= "User实体类参数")
public class User {
    @ApiModelProperty(value = "用户名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "邮箱")
    private String email;
}

Swagger 2.X

Swagger2简介

**官网：**https://swagger.io/

优点：

  1. 可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
  2. 接口文档实时更新
  3. 可以在线测试

swagger2快速入门

1、使用IDEA创建一个SpringBoot项目

2、导入相关依赖（项目中使用Swagger需要springfox中的：swagger2、swagger-ui）

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

3、通过JavaConfig对Swagger2进行配置

package com.example.swagger2.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//开启Swagger2
@EnableSwagger2
@Configuration
public class SwaggerConfig {

}

4、测试访问Swagger-UI页面地址（Swagger2访问地址）：http://localhost:8080/swagger-ui.html

Swagger2配置详解

1、Swagger2配置：

  • 配置Bean实例Docket

  • 扫描接口：Docket.select()：配置扫描包和路径

package com.example.swagger2.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@EnableSwagger2 //开启Swagger2
@Configuration
public class Swagger2Config {
    /**
     * 配置了Swagger的Docket的bean实例
     *  apis(RequestHandlerSelectors.XXX)：配置要扫描的方式
     *      RequestHandlerSelectors.basePackage：指定要扫描的包
     *      RequestHandlerSelectors.any()：扫描全部
     *      RequestHandlerSelectors.none()：不扫描
     *      RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，参数是一个注解的反射对象
     *      RequestHandlerSelectors.withMethodAnnotation()：扫描方法上的注解，参数是一个注解的反射对象
     *   paths()：过滤什么路径
     *   enable()：是否启动Swagger，如果为False，则Swagger不能在浏览器中访问
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.ant("/**"))
                .build();
    }

    /**
     * 配置Swagger信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfo("SpringBoot项目Swagger的API文档",
                "只要学不死，就往死里学",
                "1.0",
                "https://liusuixing.gitee.io/",
                // 作者信息
                new Contact("lsx", "https://liusuixing.gitee.io/", "8629303@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}
  • 希望Swagger在生产环境中使用，正式发布环境不使用：
    • 判断是不是生成环境
    • 注入enable（flag）
package com.example.swagger2.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;

@EnableSwagger2 //开启Swagger2
@Configuration
public class Swagger2Config {
    @Autowired
    Environment environment;
    @Bean
    public Docket docket() {
        // 设置要显示的Swagger环境,通过environment.acceptsProfiles 判断是否处在自己设定的环境当中
        Profiles profiles = Profiles.of("dev", "text");
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.ant("/**"))
                .build();
    }

    /**
     * 配置Swagger信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfo("SpringBoot项目Swagger的API文档",
                "只要学不死，就往死里学",
                "1.0",
                "https://liusuixing.gitee.io/",
                // 作者信息
                new Contact("lsx", "https://liusuixing.gitee.io/", "8629303@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置Api文档分组

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

Swagger2常用注解

**参考：**Swagger3.X常用注解即可.

@Api：用在请求的类上，表示对类的说明（不配置默认是按类名驼峰变下划线显示）
    value：该参数没什么意义，在UI界面上也看到，所以不需要配置"
    tags：说明该类的作用，可以在UI界面上看到的注解
    description：对api资源的描述
    basePath：基本路径
    position：如果配置多个Api 想改变显示的顺序位置
    produces：如 “application/json, application/xml”
    consumes：如 “application/json, application/xml”
    protocols：协议类型，如: http, https, ws, wss.
    authorizations：高级特性认证时配置
    hidden：配置为true ，将在文档中隐藏

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value：说明方法的用途、作用
    tags：如果设置这个值、value的值会被覆盖
    notes：方法的备注说明
    description：对api资源的描述

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · div（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
    name：参数名
    value：参数说明
    required：是否必填

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

主要属性如下：

属性描述
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
description对api资源的描述（）
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, “application/json, application/xml”
consumesFor example, “application/json, application/xml”
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏

示例：

@Api(tags = "用户模块" ,description = "user module")
@RestController
@RequestMapping("/user")
public class UserController {
}
@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性：

属性描述
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
notes操作的详细描述
description对api资源的描述
basePath基本路径可以不配置
position如果配置多个Api 想改变显示的顺序位置
producesFor example, “application/json, application/xml”
consumesFor example, “application/json, application/xml”
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为true 将在文档中隐藏
response返回的对象
responseContainer这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
codehttp的状态码 默认 200
extensions扩展属性

示例：

    // @ApiOperation("分页用户列表")
    @ApiOperation(value = "分页用户列表", notes = "对用户列表进行分页")
    @GetMapping("/pageOne")
    public ResponseEntity pageOne(){
        return ResponseEntity.ok("分页用户列表");
    }
@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性：

属性描述
name属性名称
value属性值
defaultValue默认属性值
allowableValues可以不配置
required是否属性必填
access不过多描述
allowMultiple默认为false
hidden隐藏该属性
example举例子

实例：

    @ApiOperation(value = "分页用户列表", notes = "对用户列表进行分页")
    @GetMapping("/pageTwo")
    public ResponseEntity pageTwo(
            @ApiParam(value = "当前页数", required = true) @RequestParam("page") Integer page,
            @ApiParam(value = "每页显示数", required = true) @RequestParam("limit") Integer limit){
        return ResponseEntity.ok("分页用户列表");
    }
@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam也可以定义参数.

  • @ApiImplicitParams：用在请求的方法上，包含一组参数说明
  • @ApiImplicitParam：对单个参数的说明

主要属性：

属性描述
name参数名
value参数的说明、描述
required参数是否必须必填
paramType参数放在哪个地方 query --> 请求参数的获取：@RequestParam header --> 请求参数的获取：@RequestHeader path（用于restful接口）–> 请求参数的获取：@PathVariable body（请求体）–> @RequestBody User user form（普通表单提交）
dataType参数类型，默认String，其它值dataType=“Integer”
defaultValue参数的默认值

实例：

    @ApiOperation(value = "用户查询", notes = "根据用户信息查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
            @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
            @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/findUserByMobileAndPwdAndAge")
    public ResponseEntity findUserByMobileAndPwdAndAge(@RequestParam String mobile,
                                  @RequestParam String password,
                                  @RequestParam Integer age){
        return ResponseEntity.ok("用户查询");
    }
@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明

主要属性：

属性描述
code数字，例如400
message信息，例如"请求参数没填好"
response抛出异常的类

实例：

    @ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "查询成功"),
            @ApiResponse(code = 400, message = "查询失败")
    })
    @GetMapping("/findAll")
    public ResponseEntity findAll(){
        HashMap<String, String > map  = new HashMap<String, String>(){{
            put("code","200");
        }};
        return ResponseEntity.ok().body(map);
    }
@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（一般用在使用@RequestBody的场景，请求参数无法使用@ApiImplicitParam描述）

@ApiModelProperty用来描述一个Model的属性。

ApiModel：主要属性

属性名称属性类型默认值作用
value()String空自定义类的名称
description()String空为类添加长文本描述信息

ApiModelProperty：主要属性

属性名称属性类型默认值作用
value()String空定义参数描述信息
name()String空定义参数名称
required()booleanfalse定义参数是否必传
hidden()booleanfalse定义参数是否隐藏
allowEmptyValue()booleanfalse定义参数是否允许为空

实例：

@Data
@ApiModel(description= "返回响应数据")
public class ApiResult {
    @ApiModelProperty(value = "是否成功",required=true)
    private boolean success = true;

    @ApiModelProperty(value = "http状态码")
    private Integer code;

    @ApiModelProperty(value = "提示信息")
    private String message;

    @ApiModelProperty(value = "数据")
    private Object data;
}

Swagger增强神器—Knife4j

参考：https://mp.weixin.qq.com/s/4HGYX0wpBk8-p3AfFbbBVg

简单使用（在使用Swagger3的基础上）：

添加依赖：

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

经过以上简单的依赖添加之后，无需配置任何内容，我们就可以成功的使用 Knife4j 了。

访问 Knife4j 的主页： http://localhost:8080/doc.html

SpringBoot集成Swagger3--在线API文档（详细步骤+图解）
撸码社区的博客
04-13 4936
SpringBoot集成Swagger3–在线API文档（详细步骤+图解） Open API OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。 Swagger swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。 国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3） swagger2的包
Swagger正确打开方式（一）Swagger2.X升级到Swagger3.X
热门推荐
bihaiyanyu的专栏
11-24 1万+
之前有用过swagger，但是总感觉不够灵活所以最终选择放弃了。虽然能帮忙省不少下写接口文档和维护接口文档的时间，但是一样的带来了很多的不便利性，比如我的一个接口，不同场景请求参数不一样，通过swagger自动生成的文档很难方便的帮我区分出来，还有我的返回不同错误编码具有不同的业务属性，具体业务说明我很难通过swagger进行自定义。所以我之前一直喜欢用markdown写接口文档，也用过好几个第三方提供的接口文档管理工具。最近工作稍许空下来了，而且好几个同事朋友反复向我推荐swagger，乘着最近刚起一个.
Spring Boot整合集成Swagger3.x
最新发布
m0_71973935的博客
09-30 436
这两天学了一下Swagger，在SpringBoot整合Swagger的时候遇到点问题，在网上搜集了很多资料以后，发现Swagger3.x和Swagger2.x用法的一些区别。如果使用不正确，在访问swagger-ui.html会出现404的问题以整合Swagger为主，按照步骤，同时说明与Swagger2.x的一些区别。
SpringBoot配置Swagger3.0 附带doc.html
Yue_
09-29 369
【代码】SpringBoot配置Swagger3.0 附带doc.html。
Swagger3.X 接口文档（一）
分享我的点点滴滴，在成长路上与你同行！
09-09 3474
接口文档 谁产生和维护 接口开发人员，后端工程师 谁使用 1.前端工程师 2.测试工程师 3.产品经理 接口存在的问题 接口文档不存在，靠抓包获取 接口更换后不及时更新 接口文档写错，注解写错 自动生成文档工具在跨语言不兼容 OpenApi规范：声明了用于文档的规范的版本 网址：https://github.com/OAI/OpenAPI-Specifica...
Swagger3.X 接口文档 (二)
分享我的点点滴滴，在成长路上与你同行！
09-10 1687
一、Swagger3.x对象注解ApiModel讲解 APiModel和ApiModelProperty对象注解介绍 @ApiModel() 用于类表示对类进行说明，用于参数用实体类接收，value–表示对象名，description–描述 这种一般用在post创建的时候，使用对象提交这样的场景 @ApiModelProperty() 用于方法，字段； 表示对model属性的说明或者数据操作更改 value–字段说明 name–重写属性名字 dataType–重写属性类型 require
springboot+swagger3+mybatis-plus3.5.1代码生成+druid+log4j2【最完美】的一次配置
12-21
在本次配置中，我们将探讨如何整合SpringBoot与Swagger3、MyBatis-Plus 3.5.1、Druid和Log4j2，打造一套高效且易维护的后台系统。 Swagger3是一个强大的API文档生成工具，它可以自动生成RESTful API接口的文档，...
zwqh-Spring-Boot-2.X-master.zip
08-26
在"zwqh-Spring-Boot-2.X-master.zip"这个压缩包中，我们可能找到了一个示例项目，展示了如何在Spring Boot 2.x环境中配置和使用Swagger2。文件名"Spring-Boot-2.X"可能是项目的主要目录，包含了源代码、配置文件和...
SpringBoot集成Swagger，前后端接口文档解决方案。集成SpringDoc，支持SpringBoot3.x。
头好重好重的博客
01-21 3525
一个不断在迭代的项目，Controller层与POJO层肯定会是经常变动的，在目前前后端分离的大环境背景下有一份接口文档可以极大减少项目组成员之间的交流成本，也能支持自动化测试，但靠人工维护该文档总是不够稳妥，因此我们可以使用Swagger或SpringDoc，为响应式接口文档提供了一种解决方案。
SpringBoot+Swagger (Spring5.x swagger2.x)
混日子的慕程序猿
07-01 463
接触Java四年了。最近才拿框架跑。 springboot，终于弄出来一个。 感谢博客： https://blog.csdn.net/weixin_42953268/article/details/89383024【学习了如何新建一个springboot项目及restful接口】 https://blog.csdn.net/larger5/article/details/79478606【swagger2】 https://blog.csdn.net/larger5/article/details/7932
swagger生成html离线接口文档
04-15
swagger生成html离线接口文档swagger生成html离线接口文档
swagger-gendoc:swagger文件（yaml、json）转换为pdf、html、epub3、docbook等
04-27
项目简介 本项目主要演示了将swagger-editor编辑好的swagger.yaml或swagger.json,转换为asciidoc,继而转换成其他各种格式,如:HTML、PDF、EPUB3、DOCBOOK等 主要用到了两个maven插件: swagger2markup-maven-plugin asciidoctor-maven-plugin 如何使用 将swagger.yaml或swagger.json文件放入src/test/resources包.若是swagger.json格式的话需要修改pom.xml中定义的<swagger>属性。 mvn test 因为用到的两个插件不会自动执行,所以指定了插件执行所在的阶段为test,故maven插件目标包含test环节的命令都可以执行。执行完毕后,将在target/asciidoc下会看到生成的文档。 注意事项 若你设计的
SpringBoot 3.x + Swagger3 踩坑实录
qq_47413097的博客
04-20 1744
SpringBoot3.x + Springdoc + Knife4j + JDK17解决异常
swagger 3.0.0 集成 springboot 2.6+ 生成doc.html 和swagger-ui
huangchong0107的博客
01-14 4927
springboot 集成 swagger
Swagger3
qq_42920045的博客
06-09 620
导入pom <!--swagger, 内包含 springfox-swagger2,springfox-swagger-ui--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </depen.
java-1.swagger注解的使用
LGD
09-02 1384
@Api：用在请求的类上，表示对类的说明 tags=“说明该类的作用，可以在UI界面上看到的注解” value=“该参数没什么意义，在UI界面上也看到，所以不需要配置” 4@ApiOperation：用在请求的方法上，说明方法的用途、作用 value=“说明方法的用途、作用” notes=“方法的备注说明” @ApiImplicitParams：用在请求的方法上，表示一组参数说明 @ApiImpl...
SpringBoot整合Swagger3.0
蓝天⊙白云的博客
06-28 4697
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。Swagger 的优势支持 API 自动生成同步的在线文档：使用 Swa
【swagger】Spring 3.1.3.RELEASED（老版本）集成swagger的坑
暂七师师长常乃超
01-09 2075
       网上spring集成swagger的博客多的很啊，可为啥都感觉那么像呢？        小编的项目中，spring的版本比较怀旧，“3.1.3.RELEASED”。          我分别尝试了网上比较火的：        1）http://www.cnblogs.com/zjfjava/p/9555045.html         2）https://www.cnblo...
springboot3.x 使用swagger
10-19
Spring Boot 3.x使用Swagger需要引入Swagger依赖并进行相关配置。引用中提到了使用SpringFox和SpringDoc两种库来实现Swagger的集成。其中，SpringFox是一个开源的API文档框架，可以将Swagger集成到Spring Boot应用...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值