java集成Swagger的详细步骤

2022-08-23 13:06:16

目录

一、简介以及使用

二、整合步骤

三、注解说明

四、导出word文档

一、简介以及使用

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

官网：http://swagger.io/

解决什么问题：

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

使用方式：

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

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

二、整合步骤

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

1、引入swagger支持的jar包

<!-- swagger2  -->
        <!--swagger本身不支持spring mvc的，springfox把swagger包装了一下，让他可以支持springmvc-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

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文件夹下的资源不拦截

 <!-- 打开springMVC静态资源拦截器，不拦截swagger下的资源 -->
    <servlet-mapping>    
	     <servlet-name>default</servlet-name>    
	     <url-pattern>/swagger/*</url-pattern>    
	 </servlet-mapping>

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

  <!-- 激活@controller模式 -->

    <mvc:annotation-driven />

    <!-- 开启静态文件 默认拦截器 -->

   <mvc:default-servlet-handler/>

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<Person> selectAll(HttpServletRequest request) {
		List<Person> 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、本地导出文档效果

  • 作者：Mr_庄
  • 原文链接：https://blog.csdn.net/weixin_42165041/article/details/81077100
    更新时间：2022-08-23 13:06:16