java集成Swagger的详细步骤

目录

一、简介以及使用

二、整合步骤

三、注解说明

四、导出word文档

 

一、简介以及使用

号称：世界最流行的API框架

官网：http://swagger.io/

解决什么问题：

在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档

使用方式：

1、通过官网配置文档，一个接口一个接口编写

2、通多注解配置，动态生成json数据，由框架自动生成代码展示

二、整合步骤

项目框架要求：springmvc（springboot）+spring+maven（本文以springmvc为例）

1、引入swagger支持的jar包

        
        
            io.springfox
            springfox-swagger2
            2.6.1
        
        
            io.springfox
            springfox-swagger-ui
            2.6.1
        

2、编写swagger启动类SwaggerConfig.java

package dcc.core;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
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 //声明启动Swagger2
@EnableWebMvc //声明启动mvc
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("dcc"))//扫描的包路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("DCC API接口")//文档说明
                .version("1.0.0")//文档版本说明
                .build();
    }
}

3、开启spring整合swagger配置

    a、web.xml打开静态资源拦截器，标示swagger文件夹下的资源不拦截

 
        
	     default    
	     /swagger/*    
	  

   b、开启springmvc拦截器，以及静态文件拦截器 

4、https://github.com/swagger-api/swagger-ui/tree/v2.2.10/dist，下载swaggerUI，这里我用的是2.2.10的版本，不同的版本，引入的jar包版本不同，将下载后的文件解压，将dist目录下的文件，复制到webapp下的swagger目录中,修改index.html中文档加载的地址

window.onload = function() {
  
  // Build a system
  const ui = SwaggerUIBundle({
    //url: "http://petstore.swagger.io/v2/swagger.json",
    //主要的地址，/v2/api-docs.do由swagger框架自动生成的接口地址
    url:"http://127.0.0.1:8080/项目名称/v2/api-docs.do",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

5、编写controller注解

package com.jsinfor.controller;

import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.jsinfor.bean.Person;
import com.jsinfor.service.PersonService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;

@RestController
@RequestMapping("/person")
@Api(tags = "人员接口",description="人员文档说明",hidden=true)
public class PersonController {

	@Autowired
	private PersonService personService;
	
	@RequestMapping(value="selectAll",method=RequestMethod.POST)
	@ApiOperation(value="查询所有的人员",notes="查询所有的人员接口说明")
	@ApiImplicitParams({
		@ApiImplicitParam(name="month",value="年月，格式为：201801",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="pageSize",value="页码",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="pageNum",value="每页条数",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="empName",value="业务员名称",dataType="String", paramType = "query"),
		@ApiImplicitParam(name="orderType",value="排序类型",dataType="String", paramType = "query"),
	})
	@ApiResponse(response=Person.class, code = 200, message = "接口返回对象参数")
	public List selectAll(HttpServletRequest request) {
		List list = personService.selectAll();
		return list;
	}
	
	@RequestMapping(value="findById",method=RequestMethod.POST)
	@ResponseBody
	public Person findById(Integer id) {
		Person person = personService.findById(id);
		return person;
	}
	
}

6、打开链接，查看文档

http://localhost:8080/ssm/swagger/index.html

 

三、注释说明

1、常用注解

 @Api()用于类；

表示标识这个类是swagger的资源

 @ApiOperation()用于方法；

表示一个http请求的操作

 @ApiParam()用于方法，参数，字段说明；

表示对参数的添加元数据（说明或是否必填等）

 @ApiModel()用于类

表示对类进行说明，用于参数用实体类接收

 @ApiModelProperty()用于方法，字段

表示对model属性的说明或者数据操作更改

 @ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略

 @ApiImplicitParam() 用于方法

表示单独的请求参数

 @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiResponse 

返回参数

2、具体使用

@Api()用于类；

参数：

tags:表示说明，tags如果有多个值，会生成多个list

value:已废用

hidde:无效果

description:接口说明

代码：

界面效果：

 

@ApiOperation()用于方法；

value用于方法描述

notes用于提示内容 

tags可以重新分组（视情况而用）

代码:

文档效果：

@ApiImplicitParam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

name–参数名

value–参数说明

dataType–数据类型

paramType–参数类型

代码：

 

效果：

@ApiResponse 

返回参数说明

response：返回的对象信息

code：返回的状态信息

message：返回的文本信息

对象信息具体注释

@ApiModelProperty

对象字段说明

value：字段名称

example: 字段说明

代码如下：

 

文档效果：

 

五、导出word文档（非离线文档生成）

1、获取页面生成的json数据

2、将json数据，导入到官方生成文档

3、导出word到本地

具体操作:

1、打开F12，查看页面请求生成的json，复制出json数据

2、将数据复制出来，在本地创建json文件，编码必须为UTF-8

3、打开官网，导入json，地址为：http://www.sosoapi.com/

4、查看详情，可以看到导出格式

5、本地导出文档效果

五、代码下载

通过码云git下载代码，地址如下：

ssm纯净版：https://gitee.com/zhuangwj/ssmdemo/tree/master/

ssm+swagger纯净版:

https://gitee.com/zhuangwj/ssmdemo/tree/ssmswagger/