swagger对接

举报
俺想吃蜂蜜 发表于 2022/04/13 08:09:57 2022/04/13
【摘要】 概述项目采用前后台分离的架构进行开发,后台可以使用Swagger,生成在线API文档,方便前端人员对接使用Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger官网配置生成的在线API文档样例:springfox,是一个开源的API Doc的框架,它的前身是swagger-springmvc,可以将我们的Controlle...

概述

项目采用前后台分离的架构进行开发,后台可以使用Swagger,生成在线API文档,方便前端人员对

接使用

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger官网
image.png

配置生成的在线API文档样例:

image.png

springfox,是一个开源的API Doc的框架,它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现。

springfox官网

image.png

springfox-swagger2,它是整合springmvc和swagger2的一个项目,项目中使用swagger时,要引入它的依赖

image.png

image.png

使用

在springboot中,使用Swagger非常简单,引入依赖,并做出少量的固定配置即可

例如,新建项目springboot-swagger,如下

image.png

1.pom文件,引入依赖swagger2的依赖
<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0

https://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>2.4.0</version>

<relativePath/> <!-- lookup parent from repository -->

</parent>

<groupId>com.briup.demo</groupId>

<artifactId>springboot-swagger</artifactId>

<version>0.0.1-SNAPSHOT</version>

<name>springboot-swagger</name>

<description>Demo project for Spring Boot</description>

<properties>
<java.version>1.8</java.version>

</properties>

<dependencies>

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<!-- 引入swagger相关依赖 -->

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

</dependencies>

<build>

<plugins>

<plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

</project>
2、使用配置类,对swagger进行配置
package com.briup.cms.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;

//开始springboot中对swagger2的支持

@EnableSwagger2

@Configuration
public class Swagger2Config {

//配置需要扫描的Controller的包路径

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.briup.cms.web.controller"))

.paths(PathSelectors.any())

.build();

}

//swagger界面中显示的基本信息

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("swagger在线API")

.description("欢迎访问briup官网,http://www.briup.com")

.termsOfServiceUrl("http://www.briup.com")

.version("1.0")

.build();

}

}

注意,swagger中基本都是固定的配置,按照自己的项目情况,进行修改字符串变量即可

3、Controller中使用swagger相关注解,进行辅助说明
package com.briup.cms.web.controller;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.RestController;

import com.briup.cms.util.Result;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

@Api(tags = "测试模块")

@RestController

public class HelloController {

@ApiOperation(value = "hello测试",notes = "第一个swagger测试程序")

@ApiImplicitParams({

@ApiImplicitParam(name = "name",value = "用户名",dataType =

"String",required = true,defaultValue = "tom",paramType = "query"),

})

@GetMapping("/hello")

public Result hello(String name) {

if("tom".equals(name)) {
throw new RuntimeException("异常测试...");

}

return Result.success("hello world!"+name);

}

}

其中:

  • @Api ,用来指定当前API模块的名称

  • @ApiOperation ,用来设置API方法的简介说明

  • @ApiImplicitParams ,用来设置API方法的参数,可以有多个参数

  • @ApiImplicitParam ,用来设置一个参数的详细信息

      name,参数的名称
    
      value,参数的介绍
    
      dataType,参数的数据类型,例如String
    
      required,是否为必须参数
    
      defaultValue,默认填入输入框的值
    
      paramType,参数的类型:path、query、body、header、form
    

注意,这些注解配置,都是可以不写的,swagger也能自动扫描这个Controller及其处理方法,并生

成文档

4、启动项目,访问固定地址:http://127.0.0.1:8989/swagger-ui.html

image.png

image.png

此时,就可以使用swagger的在线文档,对Controller中暴露出来的API进行测试了。该项目中其他类,都

是起到辅助作用,对本例中swagger的使用,没有任何影响。具体代码可查看项目实例。

【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。