Spring Boot入门系列之：八、Spring Boot整合swagger

太过爱你忘了你带给我的痛 2022-04-23 00:26 197阅读 0赞

# spring-boot-swagger #

## 开发环境 ##

开发工具： Intellij IDEA 2018.2.6

springboot: 2.0.7.RELEASE

jdk： 1.8.0\_192

maven: 3.6.0

swagger: 2.9.2

## swagger 简介 ##

**什么是 swagger ？**

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

**Swagger是一组开源项目，其中主要模块如下：**

*  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资源声明以各种语言生成客户端代码。

## 搭建项目 ##

*  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">
        <parent>
            <artifactId>spring-boot-examples</artifactId>
            <groupId>com.andy</groupId>
            <version>1.0.7.RELEASE</version>
        </parent>
        <modelVersion>4.0.0</modelVersion>
    
        <artifactId>spring-boot-swagger</artifactId>
    
        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>io.spring.platform</groupId>
                    <artifactId>platform-bom</artifactId>
                    <version>Cairo-SR7</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>
    
        <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.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.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.8.0</version>
                    <configuration>
                        <source>1.8</source>
                        <target>1.8</target>
                        <encoding>UTF-8</encoding>
                    </configuration>
                </plugin>
    
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <configuration>
                        
                        <layout>ZIP</layout>
                    </configuration>
                    <executions>
                        <execution>
                            <goals>
                                <goal>repackage</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    
    </project>

*  application.yml

# swagger 无须太多配置这里只是简单的配置了工程名
    swagger:
    # 是否让浏览器可以访问swagger页面
      show: true

*  启动类

import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * @author Leone
     * @since 2018-05-29
     **/
    @EnableSwagger2
    @SpringBootApplication
    public class SwaggerApplication {
        public static void main(String[] args) {
            SpringApplication.run(SwaggerApplication.class);
        }
    }

*  SwaggerConfig.java

import com.google.common.base.Predicates;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.stereotype.Component;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    import java.util.Collections;
    
    import static springfox.documentation.builders.RequestHandlerSelectors.basePackage;
    
    /**
     * @author Leone
     * @since 2018-07-12
     **/
    @Component
    public class SwaggerConfig {
    
        @Value("${swagger.show}")
        private Boolean enable;
    
        @Bean
        public Docket swaggerApi() {
            Parameter parameter = new ParameterBuilder()
                    .name("Authorization")
                    .description("token")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(false)
                    .defaultValue("token ")
                    .build();
            return new Docket(DocumentationType.SWAGGER_2)
                    .enable(enable)
                    .apiInfo(apiInfo())
                    .groupName("web-API")
                    .globalOperationParameters(Collections.singletonList(parameter))
                    .select()
                    .apis(basePackage("com.andy"))
                    .paths(Predicates.alwaysTrue())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("API")
                    .description("web接口文档")
                    .version("v1.0.0")
                    .termsOfServiceUrl("http://www.baidu.com")
                    .contact(new Contact("leone", "https://leone.com", "leone@gmail.com"))
                    .license("Apache2.0")
                    .licenseUrl("http://www.apache.org")
                    .build();
        }
    }

*  ApiController.java

import com.andy.swagger.entity.UserDTO;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.*;
    
    /**
     * @author Leone
     * @since 2018-07-12
     **/
    @RestController
    @Api(tags = "文档接口:crud测试")
    @RequestMapping("/api/user")
    public class ApiController {
    
        @ApiOperation("查询用户列表")
        @GetMapping("/list")
        public String list(@ApiParam("当前页") @RequestParam Integer page, @RequestParam Integer size) {
            return "list";
        }
    
        @ApiOperation("保存用户")
        @PostMapping
        public String save(@RequestBody UserDTO userForm) {
            return "save";
        }
    
        @ApiOperation("删除用户")
        @DeleteMapping
        public String delete() {
            return "delete";
        }
    
        @ApiOperation("修改用户")
        @PutMapping
        public String update() {
            return "update";
        }
    
    }

*  User.java

import java.io.Serializable;
    import java.util.Date;
    
    /**
     * @author Leone
     * @since 2018-07-12
     **/
    public class User implements Serializable {
    
        private Long userId;
    
        private String account;
    
        private String password;
    
        private String description;
    
        private Integer age;
    
        private Date createTime;
    
        private boolean deleted;
    
        public User() {
        }
    
        public User(Long userId, String account, String password, String description, Integer age, Date createTime, Boolean deleted) {
            this.userId = userId;
            this.account = account;
            this.password = password;
            this.description = description;
            this.age = age;
            this.createTime = createTime;
            this.deleted = deleted;
        }
    
        // getset
    }

*  UserService.java

package com.andy.swagger.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import java.util.Date;
    
    /**
     * @author Leone
     * @since 2018-07-12
     **/
    @ApiModel
    public class UserDTO {
    
        @ApiModelProperty(value = "用户账号")
        private String account;
    
        @ApiModelProperty(value = "密码")
        private String password;
    
        @ApiModelProperty(value = "生日")
        private Date birthday;
    
        @ApiModelProperty(value = "工资")
        private Double salary;
    
        @ApiModelProperty(value = "创建时间")
        private Date createTime;
    
        @ApiModelProperty(value = "是否删除")
        private Boolean deleted;
    
        // getset
    
    }

*  UserVO.java

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import java.util.Date;
    
    /**
     * @author Leone
     * @since 2018-07-12
     **/
    @ApiModel
    public class UserVO {
    
        @ApiModelProperty(value = "主键",example = "1200L")
        private Long userId;
    
        @ApiModelProperty("账号")
        private String account;
    
        @ApiModelProperty("自我介绍")
        private String description;
    
        @ApiModelProperty("年龄")
        private Integer age;
    
        @ApiModelProperty("创建时间")
        private Date createTime;
    
        // getset
    
    }

[传送门][Link 1]

[Link 1]: https://github.com/janlle/spring-boot-examples