Swagger介绍、使用Swagger注解生成API文档


Swagger介绍

引言

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。

前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档

1.什么是Swagger

Swagger就是一个用来定义接口标准,接口规范,同时能根据你的代码自动生成接口说明文档的一个工具

作为Java服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

在这里插入图片描述

2. 官方提供的工具

在这里插入图片描述

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多种语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI : 提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多,是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。

Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。

Springfox Swagger: Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的,在这里列出来做个说明,方便后面作一个使用的展开。

3.构建Swagger与SpringBoot环境

3.1 引入依赖

<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.2 编写Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.baizhi.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger")
                        .description("SpringBoot整合Swagger,详细信息......")
                        .version("9.0")
                        .contact(new Contact("xiaochen","www.baizhiedu.xin","xiaochen@163.com"))
                        .license("The Baizhi License")
                        .licenseUrl("http://www.baizhiedu.com")
                        .build());
    }
}

3.3 启动springboot应用

在这里插入图片描述

3.4 访问Swagger的UI界面

  • 访问Swagger提供的ui界面: http://localhost:8080/swagger-ui.html

在这里插入图片描述


4.使用Swagger构建

1.开发Controller接口

@RestController
@RequestMapping("user")
public class UserController {
    @GetMapping("findAll")
    public Map<String,Object> findAll(){
        HashMap<String, Object> map = new HashMap<>();
        map.put("msg","查询所有成功");
        map.put("state",true);
        return map;
    }   
}

2.重启项目访问接口界面

在这里插入图片描述

5.Swagger的注解

5.1 @Api

  • 作用: 用来指定接口的描述文字

  • 修饰范围: 用在类上

    @RequestMapping("user")
    @Api(tags = "用户模块接口规范说明")
    public class UserController {
    	....
    }
    

5.2 @ApiOperation

  • 作用: 用来对接口中具体方法做描述

  • 修饰范围: 用在方法上

    @GetMapping("findAll")
    @ApiOperation(value = "查询所有用户接口",
                  notes = "<span style='color:red;'>描述:</span>&nbsp;用来查询所有用户信息的接口")
    public Map<String,Object> findAll(){
      Map<String, Object> map = new HashMap<String,Object>();
      map.put("success","查询所有成功!");
      map.put("state",true);
      return map;
    }
    

    value: 用来对接口的说明

    notes:用来对接口的详细描述

5.3 @ApiImplicitParams

  • 作用: 用来接口的中参数进行说明

  • 修饰范围: 用在方法上

    @ApiImplicitParams({
      @ApiImplicitParam(name="id",value = "用户id",dataType = "String",defaultValue = "21"),
      @ApiImplicitParam(name="name",value = "用户姓名",dataType ="String",defaultValue = "张三")
    })
    public Map<String, Object> save(String id, String name) {
      .....
    }
    

5.4 @ApiResponses

  • 作用:用于请求的方法上,表示一组响应

  • 修饰范围: 用在方法上

    @ApiResponses({
                @ApiResponse(code = 400, message = "请求参数没填好"),
                @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    public Map<String, Object> save(String id, String name) {
      .....
    }
    
Swagger是一个用于设计和记录RESTful API的工具。它可以通过注释和注解自动生成API接口文档,使得开发者和团队成员能够更方便地查看和使用API。以下是使用Swagger生成API接口文档的基本步骤: 1. **引入Swagger依赖**: 首先,需要在项目中引入Swagger的相关依赖。以Java的Spring Boot项目为例,可以在`pom.xml`文件中添加以下依赖: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 2. **配置Swagger**: 在项目中创建一个配置类,启用Swagger并配置基本信息: ```java 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.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo")) .paths(PathSelectors.any()) .build(); } } ``` 3. **编写API接口**: 在控制器类中使用Swagger注解来描述API接口。例如: ```java import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api") @Api(value = "用户API", description = "用户相关的API接口") public class UserController { @GetMapping("/users") @ApiOperation(value = "获取用户列表", notes = "获取所有用户的详细信息") public List<User> getUsers() { return userService.getAllUsers(); } @PostMapping("/users") @ApiOperation(value = "创建用户", notes = "创建一个新的用户") public User createUser(@RequestBody User user) { return userService.createUser(user); } } ``` 4. **访问Swagger UI**: 启动应用后,可以在浏览器中访问`http://localhost:8080/swagger-ui/`来查看自动生成API文档。 通过以上步骤,Swagger可以自动生成详细的API接口文档,极大地方便了前后端开发人员的协作。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

white camel

感谢支持~

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值