SpringBoot(3) - - SpringBoot整合Swagger2

項目地址:https://github.com/zhaopeng01/springboot-study/tree/master/study3

在後端開發中經常需要對移動客戶端提供RESTful API接口，在後期版本快速迭代的過程中，修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致寫出的代碼與接口文檔不一致現象。
爲了前後臺更好的對接,爲了以後交接方便,爲了不再長篇大論的手寫api文檔,那麼就來用Swagger吧(不是打廣告),它可以輕鬆的整合到Spring中,它既可以減少我們手寫api文檔的時間，同時又將說明文檔整合到我們的代碼中,這樣前臺看着也方便,後臺工作也舒坦,
Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單(其他好處網上自己搜在這裏就不再多說了)。
Swagger也提供了強大的頁面測試功能來調試每個寫好的接口：

其他的不說了，想要了解更多的Swagger優缺點的,自行百度或者去Swagger官網
我們這裏說的是使用SpringBoot整合Swagger2來生成接口文檔的實現

1.環境

SpringBoot 2.0.4.RELEASE
Swagger 2.6.1
JDK 1.8

2.依賴

<?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.zyc</groupId>
    <artifactId>mybatis_plus2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

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

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.4.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>
		<dependencies>
	        <dependency>
	            <groupId>org.springframework.boot</groupId>
	            <artifactId>spring-boot-starter-web</artifactId>
	        </dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		 
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>
	</dependencies>
	 <build>
	        <plugins>
	            <plugin>
	                <groupId>org.springframework.boot</groupId>
	                <artifactId>spring-boot-maven-plugin</artifactId>
	            </plugin>
	        </plugins>
	    </build>

</project>

3.Swagger配置Bean

package com.zyc.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;

/**
*
* @Description:
* @author zp
* @email [email protected]
* @date 2018/8/9 13:49 
*
*/
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zyc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger構建api文檔")
                .description("簡單優雅的restfun風格，http://blog.csdn.net/saytime")
                .termsOfServiceUrl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }

}

@Configuration會被項目啓動加載爲配置類,等同於XML中配置的beans；
@Bean標註方法等同於XML中配置的bean。

啓動類中加入@EnableSwagger2 代表swagger開啓:


package cn.zyc;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@SpringBootApplication
@EnableSwagger2
public class APP{
 
	public static void main(String[] args) {
		SpringApplication.run(APP.class, args);
	}

4.定義restful接口

package com.zyc.controller;

import com.zyc.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;


@RestController
@RequestMapping(value = "/user")
@Api(value = "用戶測試模塊")
public class UserController {

    @ApiOperation(value = "添加用戶", notes = "根據參數添加用戶")
    @PostMapping(value = "/add")
    public Object getUser() {
        return new User("zyc", "123123", "1761110");
    }
}

5.實體類

package com.zyc.model;

import java.io.Serializable;

public class User implements Serializable {
    private Integer userId;

    private String userName;

    private String password;

    private String phone;

    public User() {
    }

    public User(String userName, String password, String phone) {
        this.userName = userName;
        this.password = password;
        this.phone = phone;
    }

    public User(Integer userId, String userName, String password, String phone) {
        this.userId = userId;
        this.userName = userName;
        this.password = password;
        this.phone = phone;
    }

    public Integer getUserId() {
        return userId;
    }

    public void setUserId(Integer userId) {
        this.userId = userId;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName == null ? null : userName.trim();
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password == null ? null : password.trim();
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone == null ? null : phone.trim();
    }
}

6.啓動

啓動項目訪問 http://localhost:8080/swagger-ui.html

這個時候,swagger的ui就展現到了你的面前,和上面的圖一樣

7.Swagger常用註解

- @Api()用於類； 
表示標識這個類是swagger的資源 
- @ApiOperation()用於方法； 
表示一個http請求的操作 
- @ApiParam()用於方法，參數，字段說明； 
表示對參數的添加元數據（說明或是否必填等） 
- @ApiModel()用於類 
表示對類進行說明，用於參數用實體類接收 
- @ApiModelProperty()用於方法，字段 
表示對model屬性的說明或者數據操作更改 
- @ApiIgnore()用於類，方法，方法參數 
表示這個方法或者類被忽略 
- @ApiImplicitParam() 用於方法 
表示單獨的請求參數 
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

具體使用舉例說明： 
@Api() 
用於類；表示標識這個類是swagger的資源 
tags–表示說明 
value–也是說明，可以使用tags替代 
但是tags如果有多個值，會生成多個list

外話

關於SpringBoot的教程在我之前也有很多大佬寫過了,我也是來作爲一個個人的筆記來進行記錄,如有雷同,還望海涵,希望可以給大家帶來幫助 ~ ~&

虛心的去學習,自信的去工作~

SpringBoot(3) - - SpringBoot整合Swagger2

1.環境

2.依賴

3.Swagger配置Bean

4.定義restful接口

5.實體類

6.啓動

外話

前端使用 Konva 實現可視化設計器（13）- 折線 - 最優路徑應用【思路篇】

SpringBoot(13) - - SpringBoot 自定義異常處理

SpringBoot(1) - - 搭建第一個SpringBoot工程

SpringBoot(2) - - SpringBoot熱部署

阿里雲服務器Centos7-Jenkins環境搭建(五)

SpringBoot(9) - - SpringBoot整合Mybatis

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結