使用swagger生成API说明文档

本文由个人总结，如需转载使用请标明原著及原文地址

SwaggerDemo，jar包使用maven进行管理，还没了解maven的小伙伴可能有无法使用的情况

在做前后端分离的项目时，后端人员总是要写接口文档给其他使用者，大家都知道，写接口文档是一件吃力不讨好的事，而swagger就是为了解决这个问题而存在的，不仅能提供接口文档，还能提供简单的传参测试

要使用swagger，首先你要有一个spring项目

1.导包

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>

我这使用maven统一管理jar包，在pom.xml中加入上面两个dependency，maven就能自动下载对应jar包，不了解maven的小伙伴自行在百度上找jar包，然后手动导入项目

springfox-swagger2-vesion.jar

springfox-swagger-ui-vesion.jar

2.写一个swagger配置类

package cn.ycyy.controller;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author Devil
 * @create 2018-09-26 19:16
 */
@EnableSwagger2
@ComponentScan(basePackages = {"cn.ycyy.controller"})
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport{
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("《SwaggerDemo的演示案例--》")//标题
                .description("description:项目摘要")//描述
                .termsOfServiceUrl("http://www.google.com.hk")//（不可见）条款地址，公司内部使用的话不需要配
                .contact(new Contact("Devil", "https://blog.csdn.net/qq_36911145", "[email protected]"))//作者信息
                .version("6.6.6")//版本号
                .build();
    }
}

创建的SwaggerConfig要继承WebMvcConfigurationSupport

@EnableSwagger2	swagger2启动注解
@ComponentScan(basePackages = {"cn.ycyy.controller"})	指定需要生成API文档的类所在的包路径
@Configuration	声明这是一个配置类

createRestApi方法不需要更改，主要用于swagger的初始化设置，包括扫描API注解路径等，用我提供的createRestApi默认扫描当前项目全部路径，这里的扫描与上面的@ComponentScan不同，这里扫描的不会显示在swagger-ui（swaggerAPI文档可视化界面，最后会说）上

apiInfo里的参数设置对应效果如下图所示

SwaggerConfig文件必须放在spring注解扫描器能扫描到的位置，例如说我的项目都放在cn.ycyy项目下，我指定扫描路径cn.ycyy那么spring就能把整个项目的注解都扫描到

    <context:component-scan base-package="cn.ycyy">
		<context:exclude-filter type="annotation"
			expression="org.springframework.stereotype.Controller" />
	</context:component-scan>

然后将项目启动发布到tomcat上，就能访问swaggerAPI了

扫描二维码关注公众号，回复： 3420481 查看本文章

访问的URL也是个固定的格式

http://ip地址:端口/项目名/swagger-ui.html#/

3.配置api生成

在先前说了，这里只会显示@ComponentScan(basePackages = {"cn.ycyy.controller"})，这个路径下的类生成的API

我的测试案例中只写了一个UserController所以这里只显示，UserController及里面的方法

UserController代码如下

package cn.ycyy.controller;

import cn.ycyy.bean.User;
import cn.ycyy.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.models.HttpMethod;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import javax.validation.Valid;
import java.util.List;

/**
 * @author Devil
 * @create 2018-09-28 15:36
 */
@Controller
@Api(value="aaaaaaa",description="User的相关信息接口")
public class UserController {
    @Autowired
    private UserService userService;
    @RequestMapping("/getAll")
    @ResponseBody
    @ApiOperation(value="获取所有user",notes="获取所有user，无需参数", httpMethod = "POST")
    public String getAll(){
        //查出的所有部门信息
        List<User> list = userService.selectAll();
        return list.toString();
    }
    @RequestMapping("/getOne")
    @ResponseBody
    @ApiOperation(value="获取单个user",notes="获取单个user，需参数", httpMethod = "POST")
    public String getOne(@Valid User user, BindingResult result){
        //查出的所有部门信息
        List<User> list = userService.selectBy(user);
        return list.toString();
    }
    @RequestMapping("/getOneByName")
    @ResponseBody
    @ApiOperation(value="获取单个user",notes="获取单个user，需参数", httpMethod = "POST")
    public String getOneByName(@ApiParam(value = "用户名", required = true)String name){

        return "something";
    }
}

在类上加上@Api注解

以下参数可不指定

value

在swagger-ui上不显示

description

在swagger-ui上有显示，可以当做备注使用，描述这个类的信息

在新版本的swagger2中description已被淘汰，可以用tags代替，但是不更改也不会影响使用

在方法上加上@ApiOperation注解

以下参数可不指定

value	未展开状态方法备注信息
notes	展开状态下方法备注信息，和value相比，value是未展开状态下的备注，一般会写的比较简短，而notes可以写的比较详细
httpMethod	指定http模式，参数有"POST"、"DELETE"、"GET"、"HEAD"等

如果方法需要前端传递参数，可使用@ApiParam注解

value	参数备注信息
required	是否为必填项true为必填

如果方法用对象入参的话，在实体类中对属性加@ApiModelProperty注解

value

类属性备注信息

例如我有个方法的参数用User，那么我User类如下配置

package cn.ycyy.bean;

import io.swagger.annotations.ApiModelProperty;

/**
 * @author Devil
 * @create 2018-09-28 15:24
 */
public class User {
    @ApiModelProperty(value="用户名")
    private String name;
    @ApiModelProperty(value="密码")
    private String password;
    @ApiModelProperty(value="性别")
    private String gender;
    @ApiModelProperty(value="年龄")
    private Integer age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

效果如下所示

API文档中会将User自动分解成User的属性

4.注解全参数

以下是swagger2注解中的全参数，有兴趣可以都试试

@Api
Api 标记可以标记一个Controller类做为swagger 文档资源，使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation每一个url资源的定义,使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
extensions	扩展属性

@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

@ApiImplicitParam对容器的描述

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认值
allowableValues	可以不可配置
required	是否属性必填
access	不可过多描述
allowMutiple	默认为false
dataType	数据类型
paramType	参数类型

@ApiResponse

属性名称	备注
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置