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

概述

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

接使用

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

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

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

springfox官网

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

使用

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

例如，新建项目springboot-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>

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

此时，就可以使用swagger的在线文档，对Controller中暴露出来的API进行测试了。该项目中其他类，都是起到辅助作用，对本例中swagger的使用，没有任何影响。具体代码可查看项目实例。