架构实战篇（二）：Spring Boot 整合Swagger2

作者: IT实战联盟咖啡 | 来源:发表于2018-02-01 16:43 被阅读170次

架构实战篇（二）：Spring Boot 整合Swagger2
Swagger2创建接口文档
spring boot admin导致swagger-ui.ht
SpingBoot 集成 Swagger2
Spring Boot 揭秘与实战之RabbitMQ
spring boot + swagger2 自动生成文档
Spring Boot 与 Dubbo整合
Elasticsearch之springboot集成及使用
第四章-高级整合应用1：导航
Spring Boot整合swagger2

你还在跟前端对接上花费很多的时间而没有效果吗？
你还在为写接口文档而烦恼吗？

今天就教大家一个接口对接神器 Swagger
Swagger 可以帮我们快速的展示接口的定义以及快速接口的调用测试

先让我们看下这个神器的真面目吧

是不是发现都有哪些接口一目了然？

下面就让我们的项目集成上Swagger2吧

默认我们这些东西都是需要有的： Jdk1.6+，Maven

完整的目录结构如下图

目录结构

增加Maven 依赖

<?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.example</groupId>
    <artifactId>spring-boot-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.1.RELEASE</version>
    </parent>

    <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.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>org.apache.tomcat.embed</groupId>
            <artifactId>tomcat-embed-jasper</artifactId>
        </dependency>
        <!-- 打war包用 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <packaging>war</packaging>
    <!-- -->
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <build>
        <!-- 打war包用 -->
        <finalName>swagger</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <!-- 打war包用,maven打包的时候告诉maven不需要web.xml,否刚会报找不到web.xml错误 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.1.1</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
            <!-- -->
        </plugins>
    </build>
</project>

springfox-swagger2 是主要核心， springfox-swagger-ui 是官网提供的免费UI界面

增加Spring boot 入口

package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

```properties
server.port=8081
server.context-path=/swagger
swagger.enable=true

使用注解配置Swagger

package com.example.configuration;
import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.sql.Timestamp;
import java.util.Date;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    public static final String BASE_PACKAGE = "com.example";

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 生产环境的时候关闭 swagger 比较安全
                .enable(enableSwagger)
                //将Timestamp类型全部转为Long类型
                .directModelSubstitute(Timestamp.class, Long.class)
                //将Date类型全部转为Long类型
                .directModelSubstitute(Date.class, Long.class)
                .select()
                // 扫描接口的包路径，不要忘记改成自己的
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger RESTful APIs")
                .description("Swagger API 服务")
                .termsOfServiceUrl("http://swagger.io/")
                .contact(new Contact("Swagger", "127.0.0.1", "qiaohhgz@163.com"))
                .version("1.0")
                .build();
    }
}

正常项目上线后应该是关闭掉 swagger 的，所以这边增加了一个配置 enableSwagger
可以使用 directModelSubstitute 做一些期望的类型转换

增加两个Java 传输对象

package com.example.model;

import com.fasterxml.jackson.annotation.JsonIgnore;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户")
public class User {
    @ApiModelProperty("编号")
    private Long id;

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("姓")
    private String firstName;

    @ApiModelProperty("名")
    private String lastName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty(hidden = true)// 密码不传输
    @JsonIgnore
    private String password;

    @ApiModelProperty("状态")
    private Integer userStatus;

    // 省略了get set
}

ApiModelProperty 只设置value 值的时候可以不写 value = ""
password 我们用了 JsonIgnore 和 hidden = true 设置，不希望密码传输到前端去

package com.example.model;

import io.swagger.annotations.ApiModelProperty;

public class UserForm {
    @ApiModelProperty(value = "用户名", required = true, example = "admin")
    private String username;
    @ApiModelProperty(value = "密码", required = true, example = "000000")
    private String password;

    // 省略了get set
}

使用 example 可以提供一些测试内容，方便测试

编写一个首页的Controller

package com.example.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Api(value = "首页", description = "首页")
@RequestMapping("/")
@RestController
public class IndexController {
    @ApiOperation(value = "Hello Spring Boot", notes = "Hello Spring Boot")
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String index() {
        return "Hello Spring Boot";
    }

    @ApiOperation(value = "API 页面", notes = "接口列表")
    @RequestMapping(value = "/api", method = RequestMethod.GET)
    public void api(HttpServletResponse response) throws IOException {
        response.sendRedirect("swagger-ui.html");
    }
}

为了方便访问swagger ui 页面，我们做了一个重定向 api 更方便些

再来一个常用的简单登录Controller

package com.example.controller;
import com.example.model.User;
import com.example.model.UserForm;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "用户", description = "用户")
@RequestMapping("/user")
@RestController
public class UserController {

    @ApiOperation(value = "登录", notes = "输入用户名和密码登录")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK", response = User.class, responseContainer = "user"),
            @ApiResponse(code = 405, message = "账号名或密码错误")
    })
    @RequestMapping(value = "/login", produces = {"application/json"}, method = RequestMethod.POST)
    ResponseEntity<User> login(@RequestBody UserForm form) {
        if (!form.getPassword().equalsIgnoreCase("000000")) {
            return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
        }
        User user = new User();
        user.setId(1L);
        user.setUsername(form.getUsername());
        user.setFirstName("小");
        user.setLastName("明");
        user.setEmail("xiaoming@mail.com");
        user.setUserStatus(1);
        return ResponseEntity.ok(user);
    }
}

建议使用Spring的 ResponseEntity 类做统一的返回结果
swagger 对 response code 的支持还算好，我们可以把可能出现的异常代码都一一罗列出来，方便对接的时候对异常的处理

启动服务器，打开浏览器访问下吧

http://localhost:8081/swagger/api

使用说明

点击并查看接口

点击Model 查看返回内容的数据结构

点击Example 查看案例数据

点击Model 查看请求数据结构

点击案例可以快速设置请求内容

查看并处理异常code的描述

点击Try it out! 执行并查看结果

就这么简单！你学会了吗？

关注我们

如果需要源码可以关注“IT实战联盟”公众号并留言（源码名称+邮箱），小萌看到后会联系作者发送到邮箱，也可以加入交流群和作者互撩哦~~~！

IT实战联盟是集产品、UI设计、前后端、架构、大数据和AI人工智能等为一体的实战交流服务平台！联盟嘉宾都为各互联网公司项目的核心成员，联盟主旨是“让实战更简单”，欢迎来撩~~~

架构实战篇（二）：Spring Boot 整合Swagger2
你还在跟前端对接上花费很多的时间而没有效果吗？你还在为写接口文档而烦恼吗？今天就教大家一个接口对接神器 Swag...
Swagger2创建接口文档
Spring Boot整合Swagger2 swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化...
spring boot admin导致swagger-ui.ht
spring boot admin版本：2.1.3 swagger2版本：2.7.0 spring boot se...
SpingBoot 集成 Swagger2
Swagger2的Spring Boot Starter 方便配置Swagger2。 https://github...
Spring Boot 揭秘与实战之RabbitMQ
Spring Boot 整合 RabbitMQ Spring Boot 整合 RabbitMQ 是非常容易，只需要...
spring boot + swagger2 自动生成文档
spring boot + swagger2 自动生成文档一、配置build gradle 二、配置文件三、基...
Spring Boot 与 Dubbo整合
Spring Boot 与 Dubbo整合 Spring-Boot-With-Dubbo
Elasticsearch之springboot集成及使用
【Spring Boot】Spring Boot之使用 Spring Data Elasticsearch 整合e...
第四章-高级整合应用1：导航
RabbitMQ整合Spring AMQP RabbitMQ整合Spring Boot RabbitMQ整合Spr...
Spring Boot整合swagger2
参考： http://blog.csdn.net/amon1991/article/details/7677488...