任务 2 使用 Swagger2 实现 API
任务目的
编写代码使用 Swagger2 实现 API。Swagger2 能够根据代码自动生成 API 文档，方便前后端协作开发。使用 Swagger2 实现 API 需要使用 Spring Boot 新建 Web 项目，使用 Maven 添加 Swagger2 相关 jar 包。
任务步骤
1.新建 Spring Boot 项目
打开 Eclipse，选择【File】>【New】>【Project】。在弹出窗口中选中【Spring Starter Project】，点击【Next】。
依照下图所示进行配置，点击【Next】。
勾选【Web】下的【Spring Web】，点击【Finish】。【Spring Boot Version】保持默认，版本对实验无影响。等待项目构建完成。
2.Spring Boot 集成 Swagger2
鼠标移至 Eclipse 左侧的【Package Explorer】，选择【demo】>【pom.xml】，在<dependencies>标签下添加以下内容。使用ctrl+s键保存更改。
<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>选择【demo】>【src/main/java】>【com.example.demo】，右键单击后选择【New】>【Package】，新建“configuration”包。然后在该包内新建“Swagger2Configuration.java”文件，将该文件的内容替换为以下内容，并使用ctrl+s键保存更改。
package com.example.demo.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class Swagger2Configuration {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.build();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("name","url","email@example.com");
return new ApiInfoBuilder()
.title("Swagger2实现在线API")
.contact(contact)
.build();
}
}打开【com.example.demo】下的“DemoApplication.java”文件，将文件内容替换为以下内容，并使用ctrl+s键保存更改。
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2//开启Swagger2
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}选择【demo】>【src/main/java】>【com.example.demo】，右键单击后选择【New】>【Package】，新建“controller”包。在该包内新建“HelloController.java”文件，将文件的内容替换为以下内容，并使用ctrl+s键保存更改。
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping
public String Hello() {
return "hello world";
}
}点击如下图所示的按钮。
在【Boot Dashboard】窗口选择【local】>【demo】，点击右上角的启动按钮。
打开本机的浏览器，在地址栏输入“localhost:8080/swagger-ui.html”，按下回车键访问 API 页面。访问成功结果如下图。
回到【Boot Dashboard】窗口，点击右上角的停止按钮，关闭 Spring Boot 项目。
3.编写 API 接口
选择【demo】>【src/main/java】>【com.example.demo】，右键单击后选择【New】>【Package】新建“pojo”包，然后在该包内新建“User.java”文件，将文件的内容替换为以下内容。
package com.example.demo.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户")
public class User {
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("用户密码")
private String password;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}选择【demo】>【src/main/java】>【com.example.demo】>【controller】，右键新建“UserController.java”文件，将文件的内容替换为以下内容。
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.example.demo.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@Api(tags = "用户控制器")
@RequestMapping("/user")
@RestController
public class UserController {
@ApiOperation(value = "获取用户", notes = "填写用户名")
@ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 404, message = "404 Not Found") })
@GetMapping
public User getUser(@ApiParam(value = "用户名") @RequestParam String name) {
User user = new User();
user.setName(name);
user.setPassword("123456");
return user;
}
@ApiOperation(value = "保存用户",notes = "填写用户名与密码")
@PostMapping
public String updateUser(@ApiParam(value = "用户")@RequestBody User user) {
return "success";
}
}下表对 Swagger2 的注解进行说明。
注解 | 用途 |
|---|---|
@Api | 对 Controller 类进行说明 |
@ApiOperation | 用于请求的 Controller 类方法上 ，说明方法的用途 |
@ApiParam | 用于描述请求的参数 |
@ApiResponses | 用于请求的 Controller 类方法上 |
@ApiResponse | 用于@ApiResponses 中，描述响应信息 |
@ApiModel | 用于响应的类，表示响应数据的信息 |
@ApiModelProperty | 用于类的属性上，描述该属性 |
4.实验验证
在【Boot Dashboard】窗口选择【local】>【demo】，点击右上角启动按钮运行 Spring Boot 项目。打开本机浏览器，在地址栏输入“localhost:8080/swagger-ui.html”后按下回车键，成功访问 API 文档页面。
选择【用户控制器】>【获取用户】，点击右侧的【Try it out】。
在输入框填入“test swagger”，点击【Execute】。在下方成功出现响应的数据。
继续滚动页面，可以找到对响应信息的说明。
学员评价