★*^_^*★

暂无签名

  • 博客访问: 13867
  • 博文数量: 8
  • 博客积分: 0
  • 博客等级: 民兵
  • 技术积分: 95
  • 用 户 组: 普通用户
  • 注册时间: 2015-04-09 11:03
个人简介

★*^_^*★

文章分类
文章存档

2017年(1)

2016年(4)

2015年(3)

我的朋友
微信关注

IT168企业级官微



微信号:IT168qiye



系统架构师大会



微信号:SACC2013

订阅
热词专题

分类: Java

1、背景:

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

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

2、Spring Boot集成swagger2的步骤:

1) 新建maven Java?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添加依赖;

<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.sitech.crmpd</groupId>

<artifactId>hello-word</artifactId>

<version>0.0.1-SNAPSHOT</version>

<packaging>jar</packaging>

<properties>

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

<!-- jdk版本号,angel在这里使用1.7,修改为本地配置的jdk版本号即可 -->

<java.version>1.7</java.version>

</properties>

<!-- spring boot 父节点依赖, 引入这个之后相关的引入就不需要添加version配置, spring boot会自动选择最合适的版本进行添加。 -->

<parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.3.3.RELEASE</version>

</parent>

<dependencies>

<!-- spring boot web支持:mvc,aop... -->

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

 

<!-- Swagger -->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.2.2</version>

</dependency>

 

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.2.2</version>

</dependency>

 

<dependency>

<groupId>org.json</groupId>

<artifactId>json</artifactId>

</dependency>

</dependencies>

<build>

<plugins>

<plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

</project>

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("http://412887952-qq-com.iteye.com/")

                .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,输入地址“http://localhost:8888/hello/swagger-ui.html”,即可看到生成的api,如下图:

 

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

9) 结合前端资源生成并浏览api,在地址栏输入http://localhost:8888/hello/index.html即可访问,不过在访问之前需进行以下操作:

下载swagger ui实例,https://github.com/swagger-api/swagger-ui,将dist目录下的文件拷入项目目录src/main/resources下的static(为手动创建)文件夹下,修改index.html文件,将url改为自己项目的地址http://ip:port/上下文/v2/api-docs)如下:

访问效果如下:


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

阅读(2798) | 评论(0) | 转发(1) |
给主人留下些什么吧!~~
评论热议
请登录后评论。

登录 注册