Swagger2.0复制粘贴即可用

Swagger2.0复制粘贴即可用

文章目录

前言一、Swagger的作用和概念?

1、Swagger 的优势2、SwaggerUI 特点 二、SpringBoot集成Swagger

1、启动访问Swagger2、常用注解的使用（举例：实际项目中的运用） 三、换皮肤

前言

鉴于在实际项目中运用，也未来方便以后的使用，便记录下来，方便以后翻阅(σﾟ∀ﾟ)σ…:*☆哎哟不错哦
文章内容主要来源于度娘、B站狂神，而举的例子来源于我实际项目的摘取

一、Swagger的作用和概念?

官方地址：https://swagger.io/

​ Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务以及 集成Swagger自动生成API文档。

​ Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

1、Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

2、SwaggerUI 特点

无依赖 UI可以在任何开发环境中使用，无论是本地还是在Web端中。人性化允许最终开发人员轻松地进行交互，并尝试API公开的每个 *** 作，以方便使用。易于浏览归类整齐的文档可快速查找并使用资源和端点。所有浏览器支持 Swagger UI 在所有主要浏览器中均可使用，以适应各种可能的情况。完全可定制 通过完整的源代码访问方式以所需方式设置和调整Swagger UI。完整的OAS支持 可视化Swagger 2.0或OAS 3.0中定义的API。 二、SpringBoot集成Swagger 1、启动访问Swagger

使用Swagger
要求：jdk 1.8 + 否则swagger2无法运行（我使用的是jdk11）
步骤：
1、新建一个SpringBoot-web项目
2、添加Maven依赖

   io.springfox
   springfox-swagger2
   2.9.2



   io.springfox
   springfox-swagger-ui
   2.9.2

3、要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    
    @Bean
    public Docket createRestApi() {
        // 指定扫描包路径
        // 指定生成的文档的类型是Swagger2
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）,配置文档页面的基本信息内容
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.lm.mq.controller"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    
    private ApiInfo apiInfo() {
        Contact contact = new Contact("一个爱运动的程序员", "https://blog.csdn.net/weixin_45537947", "[email protected]");
        return new ApiInfo(
                // 标题
                "RocketMQ的在线测试",
                // 描述
                "SpringCloudAlibaba整合RocketMQ、Swagger",
                // 版本
                "v1.0",
                // 组织链接
                "https://devops.aliyun.com/organization/",
                // 联系人信息
                contact,
                // 许可
                "Apach 2.0 许可",
                // 许可连接
                "许可链接",
                // 扩展
                new ArrayList<>()
        );
    }
}

到这里运行，启动服务，访问http://localhost:8080/mq/swagger-ui.html：

2、常用注解的使用（举例：实际项目中的运用）

以上便是Swagger2的启动和访问的 *** 作，下面是编写业务需求接口：

注解描述@Api修饰整个类，描述Controller的作用@ApiOperation描述一个类的一个方法，或者说一个接口@ApiParam单个参数描述@ApiModel用对象来接收参数@ApiProperty用对象接收参数时，描述对象的一个字段@ApiResponseHTTP响应其中1个描述@ApiResponsesHTTP响应整体描述@ApiIgnore使用该注解忽略这个API@ApiError发生错误返回的信息@ApiImplicitParam一个请求参数@ApiImplicitParams多个请求参数

部分使用即效果：
例如：实体类：

@Data
@ApiModel(description = "MessageContent实体类")
public class MessageContent {
    @ApiModelProperty(value = "主题")
    private String topic;
    @ApiModelProperty(value = "消息体")
    private String messageBody;
    @ApiModelProperty(value = "队列选择")
    private String hashKey;
    @ApiModelProperty(value = "超时时间")
    private long timeout;
}

在controller中的使用（这是我在实际项目中摘取）：

@RestController
@Api(tags = "MultiTypeMQController发送多类型MQ的调用接口", description = "MultiTypeMQController | Swagger在线测试")
@Slf4j
public class MultiTypeMqSend {

    @Resource
    private RocketMQTemplate rocketMQTemplate;

    
    @ApiOperation(value="strObjTimeSyncSend 方法", notes="同步消息发送方法--syncSendByStrObjTime")
    @ApiImplicitParams({
            @ApiImplicitParam(name="topic",value="主题",required=true,dataType="String"),
            @ApiImplicitParam(name="messageBody",value="消息体",required=true,dataType="String"),
            @ApiImplicitParam(name="timeout",value="超时时间",required=true,dataType="Integer",defaultValue= "1000000L")
    })
    @PostMapping(value = "/syncSendByStrObjTime/{topic}/{messageBody}")
    public void strObjTimeSyncSend(
            @PathVariable("topic") String topic,
            @PathVariable("messageBody") String messageBody,
            Long timeout) {
        if (timeout == null) {
            timeout = 1000000L;
        }
        SendResult result = rocketMQTemplate.syncSend(topic, messageBody, timeout);
        log.info("同步发送的数据情况：" + result);
    }
}

效果：


点击Try it out进行在线测试：

填写接口所需的内容即可进行接口测试。

三、换皮肤

倘若大家不喜欢这个皮肤可以换：

    io.springfox
    springfox-swagger-ui
    2.9.2

    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.1

    com.github.caspar-chen
    swagger-ui-layer
    1.1.3

    com.zyplayer
    swagger-mg-ui
    1.0.6