在spring Boot中使用swagger-bootstrap-ui(原文)

時間  2020-06-03
標籤 spring boot 使用 swagger bootstrap 原文 欄目 Spring 简体版
原文   原文鏈接

1.swagger簡介

Swagger是一個API接口管理工具，支持在線測試接口數據，根據配置自動生成API文檔，結合spring mvc而提供界面化方法文檔的一個開源框架。html

1.1Swagger主要的項目

Swagger是一組開源項目，主要項目以下：java

Swagger-tools:提供各類與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行集成。
Swagger-js: 用於JavaScript的Swagger實現。
Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。
Swagger-ui：一個無依賴的HTML、JS和CSS集合，能夠爲Swagger兼容API動態生成優雅文檔。
Swagger-codegen：一個模板驅動引擎，經過分析用戶Swagger資源聲明以各類語言生成客戶端代碼。
Swagger-editor：可以讓使用者在瀏覽器裏以YAML格式編輯Swagger API規範並實時預覽文檔。能夠生成有效的Swagger JSON描述，並用於全部Swagger工具（代碼生成、文檔等等）中。node

2.Swagger-Bootstrap-UI簡介

Swagger-Bootstrap-UI是springfox-swagger的加強UI實現，爲Java開發者在使用Swagger的時候，能擁有一份簡潔、強大的接口文檔體驗。mysql

2.1Swagger-Bootstrap-UI核心功能

官方文檔：https://doc.xiaominfo.com/guide/#%E7%AE%80%E4%BB%8Bgit

效果：http://swagger-bootstrap-ui.xiaominfo.com/doc.html<?XML:NAMESPACE PREFIX = "[default] http://www.w3.org/2000/svg" NS = "http://www.w3.org/2000/svg" />github

示例:https://gitee.com/xiaoym/swagger-bootstrap-ui-demoweb

該UI加強包主要包括兩大核心功能：文檔說明 和 在線調試spring

  • 文檔說明：根據Swagger的規範說明，詳細列出接口文檔的說明，包括接口地址、類型、請求示例、請求參數、響應示例、響應參數、響應碼等信息，使用swagger-bootstrap-ui能根據該文檔說明，對該接口的使用狀況一目瞭然。sql

  • 在線調試：提供在線接口聯調的強大功能，自動解析當前接口參數,同時包含表單驗證，調用參數可返回接口響應內容、headers、Curl請求命令實例、響應時間、響應狀態碼等信息，幫助開發者在線調試，而沒必要經過其餘測試工具測試接口是否正確,簡介、強大數據庫

3.建立spring Boot項目

本案例是基於spring boot+jpa+mysql+swagger,編譯器選擇IDEA。

3.1建立maven 項目，引入依賴包：spring boot、swagger和swagger-bootstrap-ui依賴包

image


spring Boot父包和編碼格式設置
<!-- 定義公共資源版本 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.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>

spring boot經常使用依賴包

<dependencies>
        <!-- 上邊引入 parent，所以 下邊無需指定版本 -->
        <!-- 包含 mvc,aop 等jar資源 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!--spring操做數據庫jpa 用於將數據存入數據庫的類和方法的集-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!-- 熱部署 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <optional>true</optional>
            <scope>true</scope>
        </dependency>

        <!--spring模板引擎-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <!--數據庫相關-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
    </dependencies>

其餘

<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <!-- 沒有該配置，devtools 不生效 -->
                    <fork>true</fork>
                </configuration>
            </plugin>
        </plugins>
    </build>


引入swagger和的swagger-bootstrap-ui包

<!-- 引入swagger-ui包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

        <!-- 引入swagger包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>

        <!-- 引入swagger-bootstrap-ui包 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.3</version>
        </dependency>


所有：

<!-- 定義公共資源版本 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.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>
        <!-- 上邊引入 parent，所以 下邊無需指定版本 -->
        <!-- 包含 mvc,aop 等jar資源 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- 引入swagger-ui包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

        <!-- 引入swagger包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>

        <!-- 引入swagger-bootstrap-ui包 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.3</version>
        </dependency>

        <!--spring操做數據庫jpa 用於將數據存入數據庫的類和方法的集-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!-- 熱部署 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <optional>true</optional>
            <scope>true</scope>
        </dependency>

        <!--spring模板引擎-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <!--數據庫相關-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <!-- 沒有該配置，devtools 不生效 -->
                    <fork>true</fork>
                </configuration>
            </plugin>
        </plugins>
    </build>


3.2編寫數據表


image


3.3利用JPA編寫基本的增刪改查

在  resources 目錄下新建  application.properties 文件，內容以下

 
 
 
  
#修改tomcat默認端口號
server.port=8090

#配置數據源信息
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost:3306/jpastudy
spring.datasource.username=root
spring.datasource.password=1234567
#配置jpa
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jackson.serialization.indent_output=true
##控制檯打印sql

entitiy層

/** * @Auther: Newbe * @Date: 2019/9/24 10:34 * @Description: */ @Entity public class User { @Id @GeneratedValue(strategy= GenerationType.AUTO) private Integer id; private String username; private String password; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } 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; } }

service 接口層

package com.newbe.service; import com.newbe.entity.User; import java.util.List; import java.util.Optional; /** * @Auther: Newbe * @Date: 2019/9/24 23:48 * @Description: */
public interface UserService { //根據id查詢用戶
    Optional<User> getUserById(Integer id); //查詢全部用戶
    List<User> getUserAll(); //根據id刪除用戶
    void del(int id); //更新保存
 User save(User user); }

service impl

package com.newbe.service; import com.newbe.entity.User; import com.newbe.repository.UserDAO; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.List; import java.util.Optional; /** * @Auther: Newbe * @Date: 2019/9/24 23:53 * @Description: */ @Service public class UserServiceImpl implements UserService{ @Autowired private UserDAO userDAO; @Override public Optional<User> getUserById(Integer id) { return userDAO.findById(id); } @Override public List<User> getUserAll() { return userDAO.findAll(); } @Override public void del(int id) { userDAO.deleteById(id); } @Override public User save(User user) { userDAO.save(user); return user; } }

controller層

package com.newbe.controller; import com.newbe.entity.User; import com.newbe.service.UserService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.List; import java.util.Optional; /** * @Auther: Newbe * @Date: 2019/9/24 23:58 * @Description: */ @RestController public class UserController { @Autowired private UserService userService; @RequestMapping("/findUserById") public Optional<User> getUserById(int id){ return userService.getUserById(id); } @RequestMapping("/findAll") public List<User> findUserAll(){ return userService.getUserAll(); } @RequestMapping("/del") public void del(int id){ userService.del(id); } @RequestMapping("/save") public User save(User user){ return userService.save(user); } }

啓動類

package com.newbe; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.web.client.RestTemplateBuilder; import org.springframework.context.annotation.Bean; import org.springframework.web.client.RestTemplate; /** * @Auther: Newbe * @Date: 2019/9/25 00:05 * @Description: */ @SpringBootApplication public class UserApp { public static void main(String[] args) { SpringApplication.run(UserApp.class,args); } }

項目結構：

image


以上代碼的項目地址：https://gitee.com/fbyluohua/SwaggerStudy.git   以上是源代碼，後面直接對源代碼進行使用Swagger生成文檔

image

4.配置Swagger信息

新建config文件夾

image

SwaggerConfiguration.java
package com.newbe.comfig; 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; @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select()
//掃描端口 .apis(RequestHandlerSelectors.basePackage("com.newebe")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("swagger-bootstrap-ui RESTful APIs") .description("swagger-bootstrap-ui") .termsOfServiceUrl("http://localhost:8999/") .contact("1160285648@mail.com") .version("1.0") .build(); } }

啓動項目，在瀏覽器輸入：http://localhost:8090/doc.html


image

以上表示swagger界面生成成功，接着須要配置註釋來生成API文檔

5.添加swagger註解

爲controller層添加註解

**
 * @Auther: Newbe * @Date: 2019/9/24 23:58
 * @Description: */ @Api(value="用戶接口",description = "用戶信息接口") @RestController public class UserController { @Autowired private UserService userService; @ApiOperation(value="根據id獲取用戶信息",notes="方法備註說明") @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Integer", name = "id", value = "編號", required = true) }) @RequestMapping(value = "/findUserById", method=RequestMethod.GET ) public Optional<User> getUserById(int id){ return userService.getUserById(id); } @ApiOperation(value="查詢全部用戶信息",notes="方法備註說明") @RequestMapping(value = "/findAll", method=RequestMethod.GET ) public List<User> findUserAll(){ return userService.getUserAll(); } @ApiOperation(value="根據id刪除用戶信息",notes="方法備註說明") @RequestMapping(value ="/del", method=RequestMethod.GET) public void del(int id){ userService.del(id); } @ApiOperation(value="保存用戶信息",notes="方法備註說明") @RequestMapping(value ="/save",method=RequestMethod.GET) public User save(User user){ return userService.save(user);
    }

}

爲實體層添加註解

/** * @Auther: Newbe * @Date: 2019/9/24 10:34 * @Description: */ @ApiModel(value = "User",description = "用戶信息") @Entity public class User { @Id @GeneratedValue(strategy= GenerationType.AUTO) @ApiModelProperty(value = "用戶ID",name = "id") private Integer id; @ApiModelProperty(value = "用戶名",name = "userName") private String username; @ApiModelProperty(value = "密碼",name = "password") private String password; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } 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; } @Override public String toString() { return "User{" +
                "id=" + id +
                ", username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}'; } }

6.生成API文檔

啓動項目，在瀏覽器輸入：http://localhost:8090/doc.html

image

展開用戶接口

image

測試接口

image

測試成功，其餘接口也同樣這樣測試

image


關於項目代碼

image

7.關於API接口詳解

請參考：http://www.javashuo.com/article/p-xoxiqszl-dn.html

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程