前言技术之Swagger

最新推荐文章于 2024-09-25 21:23:51 发布

落日飞行

最新推荐文章于 2024-09-25 21:23:51 发布

阅读量640

点赞数 5

分类专栏：前言技术文章标签： java 开发语言

本文链接：https://blog.csdn.net/m0_53151031/article/details/123431678

版权

前言技术专栏收录该内容

3 篇文章 1 订阅

订阅专栏

2.1. 打开https://mvnrepository.com/ ，查找springbox，在pom.xml中导入如下图标出的依赖。

一、Swagger介绍

1、定义：

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2、为什么会用到Swagger

前后端分离是的前端与后端之间的职责更加明确后台：负责业务处理前端：负责显示逻辑在这种情况下，前端和后端可以分别交付给专业的开发人员去做，所以是必须要定义前后端直接的对接接口，否则各自为是则项目无法集成，这时就需要一个文档来定义统一的接口。

但是：在没有swagger之前

我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即：在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了作用，甚至会起到反作用。所以就诞生了Swagger

3、Swagger作用

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是在开发接口时可以通过swagger将接口文档定义好，同时也方便以后的维护。

4、Swagger优点

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是在开发接口时可以通过swagger将接口文档定义好，同时也方便以后的维护。

二、集成Swagger

1、新建springboot项目

2、集成swagger

2.1. 打开https://mvnrepository.com/ ，查找springbox，在pom.xml中导入如下图标出的依赖。

前一俩个依赖都需要：

2.2. 导入依赖

        <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>

2.3. 编写swagger的配置类

package com.example.swagger01.config;

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


@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerDemo API DOC")
                .description("SwaggerDemo API DOC")
                .version("1.0")
                .termsOfServiceUrl("https://www.baidu.com")
                .build();
    }


}

注意：该配置类需要根据自己的项目修改，如以下配置paths 指定需要生成文档的url规则title 文档标题description 描述

3、开发一个controller用于测试

package com.example.swagger01.controller;

import com.example.swagger01.pojo.User;
import com.example.swagger01.response.ResponseResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/swaggerdemo")
@Api(tags = "控制类")
public class HelloController {

    @ApiOperation(value = "欢迎信息")
    @GetMapping("/hello")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名称", dataType = "string", paramType = "query", required = true),
            @ApiImplicitParam(name = "msg", value = "消息", dataType = "string", paramType = "query", required = true)
    })
    public ResponseResult<?> hello(String name, String msg) {
        return ResponseResult.success();
    }

    @PostMapping("/register")
    @ApiOperation("注册用户接口")
    @ApiResponses({
            @ApiResponse(code = 10001, message = "Exception 01"),
            @ApiResponse(code = 10002, message = "Exception 02"),
            @ApiResponse(code = 10003, message = "Exception 03")
    })
    public ResponseResult<?> register(@RequestBody User user) {
        return ResponseResult.success();
    }

    @PutMapping("/edit")
    @ApiOperation("修改用户信息")
    public ResponseResult<?> edit(User user) {
        return ResponseResult.success();
    }

    @DeleteMapping("/delete/{id}")
    @ApiOperation("删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "path", required = true)
    public ResponseResult<?> delete(@PathVariable("id") String id) {
        return ResponseResult.success();
    }


}