Spring boot系列 -- Spring Boot集成Swagger2

1、背景：

RESTful API需要面对多个开发人员或多个开发团队，为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下问题：由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），而随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介很容易导致不一致，Swagger的产生就是为了解决以上这些问题。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。接下来看下Spring Boot是如何集成swagger2的。

2、Spring Boot集成swagger2的步骤：

1) 新建maven project;

注：新建maven项目时，需先安装maven

打开MyEclipse，file——new——project——Maven Project:

 

 

 

点击“Next”，勾选Create a simple project （不使用骨架）

 

点击“Next”，输入group Id、Artifact Id、version、packaging，点击finish即可完成maven项目创建

 

 

项目目录如下：

 

2) 在pom.xml添加依赖；

"" xmlns:xsi=""

xsi:schemaLocation=" ">

4.0.0

com.sitech.crmpd

hello-word

0.0.1-SNAPSHOT

jar

UTF-8

UTF-8

1.7

org.springframework.boot

spring-boot-starter-parent

1.3.3.RELEASE

org.springframework.boot

spring-boot-starter-web

 

io.springfox

springfox-swagger-ui

2.2.2

 

io.springfox

springfox-swagger2

2.2.2

 

org.json

json

org.springframework.boot

spring-boot-maven-plugin

3) 在pom.xml添加依赖后，需执行maven install把共用模块安装到本地maven仓库中，为避免项目报错，还需更新依赖（update dependencies）和更新项目配置（update project configuration）,选中项目，单机右键，run As中maven install，Maven4Myeclipe中找update dependencies和update project configuration，如下图；

 

4) 创建Swagger2配置类（com.sitech.crmpd.SwaggerConfig）；

package com.sitech.crmpd;

 

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 SwaggerConfig {

@Bean

    public Docket testApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(testApiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.sitech.crmpd"))

                .paths(PathSelectors.any())

                .build();

    }

 

    private ApiInfo testApiInfo() {

        return new ApiInfoBuilder()

                .title("Test相关接口")

                .description("Test相关接口，主要用于测试.")

                .termsOfServiceUrl("")

                .contact("Angel")

                .version("1.0")

                .build();

    }

}

5) 编写Controller类（com.sitech.crmpd.controller.TestController）；

package com.sitech.crmpd.controller;

 

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

 

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RequestParam;

import org.springframework.web.bind.annotation.ResponseBody;

 

@Controller

@RequestMapping("/api/test")

public class TestController {

    @ResponseBody

    @RequestMapping(value = "/show", method=RequestMethod.POST)// 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。

    @ApiOperation(value="test interface", notes="test interface descrip")

    public String show(

            @ApiParam(required=true, name="name", value="yucy")

            @RequestParam(name = "name") String stuName){

        return "success";

    }

}

6) 编写Application启动类（com.sitech.crmpd.Application）；

注：Application应放在包com.sitech.crmpd下

package com.sitech.crmpd;

 

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

import org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration;

 

@SpringBootApplication(exclude={DataSourceAutoConfiguration.class,HibernateJpaAutoConfiguration.class})

public class Application {  

    public static void main(String[] args) {  

        SpringApplication.run(Application.class,args);  

    }

  

}  

7) 在目录src/main/resources下新建application.properties文件，设置端口和上下文

server.port=8888

server.context-path=/hello/

 

8) （直接访问）启动项目application，输入地址“”，即可看到生成的api，如下图：

 

注：此处可直接访问地址浏览api文档，也可结合前端资源进行访问

9) 结合前端资源生成并浏览api，在地址栏输入即可访问，不过在访问之前需进行以下操作：

下载swagger ui实例，将dist目录下的文件拷入项目目录src/main/resources下的static（为手动创建）文件夹下，修改index.html文件，将url改为自己项目的地址（上下文/v2/api-docs）如下：

访问效果如下：

3、工程代码下载hello-word.zip