架构实战篇(二)-Spring Boot整合Swagger,让你的API可视化

我是小探花 2018-02-02 17:02:04 ⋅ 158 阅读

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

今天就教大家一个接口对接神器 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实战联盟”公众号哦~~~


全部评论: 0

    我有话说:

    架构实战(三)-Spring Boot架构搭建RESTful API案例

    之前分享了Spring Boot 整合Swagger API和前后端分离架构 受到了大家一致好评 ,本节就接着上节代码做了详细查询代码补充和完善并搭建RESTful API架构案例。

    架构实战(十七):Spring Boot Assembly 整合 thymeleaf

    如何服务器上 sprig boot 项目升级变方便快捷

    推荐一款功能强大,开源免费H5编辑器

    H5-Dooring 是一款功能强大,开源免费H5页面配置解决方案,致力于提供一套简单方便、专业可靠、无限可能H5落地页最佳实践。技术栈以react为主, 后台采用nodejs开发. 预览

    码云推荐:一个优秀分布式spring boot/Spring Cloud API限流框架,特别适合微服务架构

    一个优秀分布式spring boot/Spring Cloud API限流框架,特别适合微服务架构.

    架构实战(六):Spring Boot RestTemplate使用

    RestTemplate是Spring提供用于访问Rest服务客户端,RestTemplate提供了多种便捷访问远程Http服务方法,能够大大提高客户端编写效率。

    架构实战(十):Spring Boot 分布式Session共享Redis

    分布式Web网站一般都会碰到集群session共享问题,小编整理了一套解决方案,内附GitHub 源码地址哦~~~

    架构实战(十六):Spring Boot Assembly服务打包

    使用assembly来打包springboot微服务项目,发布更简单

    SpringBoot+zk+dubbo架构实践(五):搭建微服务电商架构(内附GitHub地址)

    集成了mybatis和swagger接口并完成了一些增删改查基础业务,对了还有个分页查询!

    架构实战(七):Spring Boot Data JPA 快速入门

    Spring Data JPA 是Spring Data 一个子项目,它通过提供基于JPARepository极大了减少了操作JPA代码。

    架构实战(十三):Spring Boot Logback 邮件通知

    日志对于应用程序来说是非常重要,当程序报错了,而又不知道是多么可怕一件事情,本文使用logback把程序报错信息邮件到开发者

    架构实战(十四):Spring Boot 多缓存实战

    多场景下不同缓存策略解决方案

    架构实战(十):Spring Boot 集成 Dubbo

    Dubbo是阿里巴巴SOA服务治理方案核心框架,一个分布式服务框架,致力于提供高性能和透明RPC远程服务调用方案。

    架构实战(一)-Spring Boot+MyBatis基础架构搭建

    Spring追求一定是简单点简单点,java开发变得更加简单、容易。瞧瞧告诉你们直接copy就能用哦~~~

    架构实战(五):Spring Boot 表单验证和异常处理

    为了API 能够更好提供服务,表单数据验证和异常处理是必不可少我们来看看怎么处理......

    架构实战(四):Spring Boot整合 Thymeleaf

    Thymeleaf 是一种模板语言。那模板语言或模板引擎是什么?

    架构实战(十五):Spring Boot 解耦之事件驱动

    通过使用spring 事件来解决业务代码耦合

    微服务架构实战(六):Spring boot2.x 集成阿里大鱼短信接口详解与Demo

    Spring boot2.x 集成阿里大鱼短信接口,发送短信验证码及短信接口详解。