看点咨询--swagger对接

俺想吃蜂蜜

发布于 2022-1-19 22:48

3704浏览

0收藏

春节不停更，此文正在参加「星光计划-春节更帖活动」

概述

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

接使用

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger官网
看点咨询--swagger对接-鸿蒙开发者社区

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

看点咨询--swagger对接-鸿蒙开发者社区

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

springfox官网

看点咨询--swagger对接-鸿蒙开发者社区

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

看点咨询--swagger对接-鸿蒙开发者社区

使用

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

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

看点咨询--swagger对接-鸿蒙开发者社区

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>
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.

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();

}

}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.

注意，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);

}

}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.

其中：

@Api ，用来指定当前API模块的名称
@ApiOperation ，用来设置API方法的简介说明
@ApiImplicitParams ，用来设置API方法的参数，可以有多个参数

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

  name，参数的名称

  value，参数的介绍

  dataType，参数的数据类型，例如String

  required，是否为必须参数

  defaultValue，默认填入输入框的值

  paramType，参数的类型：path、query、body、header、form
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

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

成文档