简介

本文主要介绍将以上三者组合，搭建简单的web服务器，并导出Human Readable的Restful API.
https://github.com/XiaoHanChina/SpringBootSwagger

一、Eclipse

只要搭建好平时的Eclipse、Java的开发环境即可。

二、Spring Boot

1.搭建Spring Boot环境

在eclipse中，Help - Eclipse Marketplace. 搜索Spring Tools,安装即可.

image.png

2.创建SpringBoot项目 Quick Start

New Project - Spring - Spring Started Project, 然后根据步骤填写包名等信息，Dependencies选择Web（带有Tomcat的Spring MVC项目）即可。

image.png

如果你之前的SpringBoot的Version是早期版本，但是上面这个界面显示的是较新的版本导致你无法创建出完整的项目，提示pom.xml有错误。则右键项目Maven install，他会帮你下载需要的包，然后右键项目Maven update Project即可。

3.编写简单的接口

新建WelcomController
在Application中添加Hello world接口，在对应的方法上加上RequestMapping的注解，在Application上添加RestController的注解。（这里在Application上添加@RequestMapping("/hxs")表明本类的所有方法都在/hxs/路径下）

@RequestMapping("/hxs")
@RestController
@SpringBootApplication
public class JianShuDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(JianShuDemoApplication.class, args);
    }

    @RequestMapping("/")//Get any visitation by this route, no matter GET, POST, DELETE, etc.
    public String hello() {
        System.out.println("Got one visitation.");
        return "Hello world!";
    }

}

测试SpringBoot

在Application上，右击，Run As - Spring Boot App.它就运行在本机的8080端口上，测试地址http://localhost:8080/hxs/，同时你的Eclipse的 控制台也会输出Got one visitation.

三、添加Swagger到项目中 官网

pom.xml中添加Springfox依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>

pom.xml中添加SwaggerUI依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>

配置Swagger，在Application中添加Dockey

Application添加@EnableSwagger2注解，类种添加Dockey Bean。（regex方法不能通过自动导包导入，需要添加静态依赖）

import static springfox.documentation.builders.PathSelectors.regex;
···
@RequestMapping("/hxs")
@RestController
@EnableSwagger2
@SpringBootApplication
public class JianShuDemoApplication {
    ...
    @Bean
    public Docket demoApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.hxs.demo"))
                .paths(regex("/hxs.*")).build();

    }

}

获取Swagger json

直接访问默认地址http://localhost:8080/v2/api-docs

获取SwaggerUI

访问默认地址http://localhost:8080/swagger-ui.html, 点击jian-shu-demo-application即可展开看到所有的API地址，并可以测试

image.png

四、进阶篇，接口注释及复杂API

添加API简介

Docket提供了apiInfo方法供我们填写一些API的简介、作者联系方式等简单信息。
首先在Application中添加meataData方法，返回ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl)

private ApiInfo metaData() {
        ApiInfo apiInfo = new ApiInfo(
                "Spring Boot REST API Demo by hxs",
                "Spring Boot REST API for Simple Demo",
                "1.0",
                "termsOfServiceUrl",
                new Contact("Xingsheng Han", "https://github.com/XiaoHanChina/SpringBootSwagger",
                        "xingsheng_han@163.com"),
               "Apache License Version 2.0",
               "https://www.apache.org/licenses/LICENSE-2.0");
        return apiInfo;
    }

然后在Docket Bean中添加

    @Bean
    public Docket demoApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.hxs.demo"))
                .paths(regex("/hxs.*"))
                .build()
                .apiInfo(metaData());

    }

重新运行，访问http://localhost:8080/swagger-ui.html即可看到API的简介，并可以通过Contact the developer给开发者发邮件

image.png

不同类型的请求方式

参数、返回值描述

Model

参考资料

Spring Swagger Quick Start: https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
源码: https://github.com/XiaoHanChina/SpringBootSwagger
Springfox Java docs: https://springfox.github.io/springfox/javadoc/current/