三分鐘搞定 Springboot 和Swagger 整合

菜鳥級的IT之路發表於2018-07-25
Spring BootSwagger

springboot這裡，我不做講解。

swagger產生背景

  在軟體開發行業，管理文件是件頭疼的事。不是文件難於撰寫，而是文件難於維護，因為需求與程式碼會經常變動，尤其在採用敏捷軟體開發模式的系統中。好的工具能夠提高團隊溝通效率，保證系統質量以及縮短專案的交付週期。反之，差的管理工具，會嚴重影響溝通效率，增加系統bug數量，並且延誤產品的上線日期。所以選用合理與合適的軟體開發文件管理工具十分重要，真正讓開發者做到“高高興興地把活幹完，早點回家吃飯打遊戲”。

   隨著網際網路技術的發展，現在的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，而且前端技術和後端技術在各自的道路上越走越遠。 
前端和後端的唯一聯絡，變成了API介面；API文件變成了前後端開發人員聯絡的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文件的框架。

swagger簡介

https://petstore.swagger.io/

https://swagger.io/

https://petstore.swagger.io/?_ga=2.213559188.1865753670.1532504182-53638988.1532504182#/

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已經形成一個生態圈，能夠管理API的整個生命週期，從設計、文件到測試與部署。Swagger有幾個重要特性：

  • 程式碼侵入式註解
  • 遵循YAML文件格式
  • 非常適合三端（PC、iOS及Android）的API管理，尤其適合前後端完全分離的架構模式。
  • 減少沒有必要的文件，符合敏捷開發理念
  • 功能強大

Swagger擁有眾多不同語言和平臺的開源實現與工具，主要有：

  • Swagger UI，基於Swagger-compliant API的一套可以展示優美文件的Web應用。
  • Swagger Editor，一款以YAML格式編輯與管理API的工具，同時支援JSON格式的文件描述。
  • Swagger-Core，Swagger的Java/Scala實現，並已整合 JAX-RS (Jersey, Resteasy, CXF...), Servlets與Play Framework。
  • Swagger-JS，Swagger的Javascript版本實現。

 

實戰開幹

 

swagger註解說明

具體程式碼

User

public class User {

    private  String username;
    private  String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

UserService

@Service
public class UserService {
    public User getUser(String username, String password) {
        User use = new User();
        use.setUsername(username);
        use.setPassword(password);
        return use;
    }
}

UserController

@RestController
@RequestMapping("/user")
@Api("userController相關api")
public class UserController {
    @Autowired
    private UserService userService;
    @ApiOperation("獲取使用者資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="使用者的姓名",defaultValue="nishisabi"),
            @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="使用者的密碼",defaultValue="nishisabi")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="請求引數沒填好"),
            @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
    })
    @RequestMapping(value="/getUser",method= RequestMethod.GET)
    public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
        return userService.getUser(username,password);
    }
}

pom.xml檔案

<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.ioc</groupId>
	<artifactId>ioc-swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>ioc-swagger</name>
	<description>Demo project for Spring Boot</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.3.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

IocSwaggerApplication

/**
 * \引入了一個註解@EnableSwagger2來啟動swagger註解。
 * （啟動該註解使得用在controller中的swagger註解生效，
 * 覆蓋的範圍由@ComponentScan的配置來指定，
 * 這裡預設指定為根路徑”com.xxx.firstboot”下的所有controller）
 */
@EnableSwagger2             //啟動swagger註解
public class IocSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(IocSwaggerApplication.class, args);
    }
}

然後啟動application類，瀏覽器訪問：http://localhost:8080/swagger-ui.html#/

點選介面 user-controller

 

ok了，溜溜了

相關文章