swagger 接口文档

原文链接：https://blog.csdn.net/weixin_37509652/article/details/80094370

方法一：使用第三方依赖（最简单的方法）

1、在pom.xml文件中添加第三方swagger依赖（）

<dependency>
  <groupId>com.spring4all</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>1.7.0.RELEASE</version>
</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目，里面有详细的讲解。

方法二：使用官方依赖

1、在pom.xml文件中添加swagger相关依赖

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //自定义方法获取文档主要信息
                .apiInfo(apiInfo())
                .select()
                //扫码文件路径
                .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                //设置路径筛选，
                // 该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与
                //pathselectors.any()返回包含满足条件的请求处理器的断言，该断言总为true
                //pathselectors.none()返回包含不满足条件的请求处理器的断言，该断言总为true
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口管理文档首页显示")
                .description("API描述")
                .termsOfServiceUrl("不可见）条款地址，公司内部使用的话不需要配")
                .license("xxx")
                .licenseUrl("xxxx")
                .version("1.0")
                .build();
    }
}

三、具体使用

1、在API上做一些声明

Swagger所有注解并非必须，若不加就只显示类目/方法名/参数名没有注释而已，但若注解中含@ApiParam不对应@RequestParam将无效果
@Api:注解controller，value为@RequestMapping路径
@ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false
@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名，value为注释，defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须，默认为false
@ApiModel:注解Model
@ApiModelProperty:注解Model下的属性，当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value
@ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示

2、设定访问API doc的路由

在配置文件中，application.yml中声明：

springfox.documentation.swagger.v2.path: /api-docs

这个path就是json的访问request mapping.可以自定义，防止与自身代码冲突。

API doc的显示路由是：http://localhost:8080/swagger-ui.html

如果项目是一个webservice，通常设定home / 指向这里：

@Controller
public class HomeController {
    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

3.项目启动后访问页面显示端口

http://服务器ip:端口/swagger-ui.html#/

四：swagger的常用API

1、api标记

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

2、ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

3、ApiParam标记
ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

4、ApiResponse响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

5、ResponseHeader响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

五:项目阶段

5.1 项目开始阶段

一般来说，接口文档都是由服务端来编写的。在项目开发阶段的时候，服务端开发可以视情况来决定是直接编写服务端调用层代码，还是写Swagger描述文件。建议是如果项目启动阶段，就已经搭好了后台框架，那可以直接编写服务端被调用层的代码（即controller及其入参出参对象），然后通过Springfox－swagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架，而前端对接口文档追得紧，那就建议先编写swagger描述文件，通过该描述文件生成接口文档。后续后台框架搭好了，也可以生成相关的服务端代码。

5.2 项目迭代阶段

到这个阶段，事情就简单很多了。后续后台人员，无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。真正做到了一劳永逸。

5.3流程(2个)

总结一下就是通过下面这两种流程中的一种，可以做到代码和接口文档的一致性，服务端开发再也不用花费精力去维护接口文档。

流程2:

给Mock系统的正常请求及响应全流程数据

很多时候，如果你能在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统，直接将这些模拟数据录入到Mock系统中，那将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。
通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细，如果你把每个出入参数的示例值都配上，那前端就可以直接在接口文档中拿到模拟数据。相关的注解类及参数配置可以参考文末他人写的技术文章，这里也不作展开了。
相关示例注解代码和效果图如下：

#####Controller代码
@Override
    @ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")
    public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
        log.info("/testPost is called. input=" + input.toString());
        return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
    }
#####接口请求入参对象   
@Data
@ApiModel(value="演示类",description="请求参数类" )
public class DemoDto implements Serializable {
    private static final long serialVersionUID = 1L;
    @NotNull
    @ApiModelProperty(value = "defaultStr",example="mockStrValue")
    private String strDemo;
    @NotNull
    @ApiModelProperty(example="1234343523",required = true)
    private Long longNum;
    @NotNull
    @ApiModelProperty(example="111111.111")
    private Double doubleNum;
    @NotNull
    @ApiModelProperty(example="2018-12-04T13:46:56.711Z")
    private Date date;
}
#####接口请求出参公共类
@ApiModel(value="基础返回类",description="基础返回类")
public class FFResponseModel<T> implements Serializable {
    private static final long serialVersionUID = -2215304260629038881L;
    // 状态码
    @ApiModelProperty(example="成功")
    private String code;
    // 业务提示语
    @ApiModelProperty(example="000000")
    private String msg;
    // 数据对象
    private T data;
...
}
#####接口请求出参实际数据对象
@Data
public class DemoOutputDto {
    private String res;
    @NotNull
    @ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
    private String outputStrDemo;
    @NotNull
    @ApiModelProperty(example="6666666",required = true)
    private Long outputLongNum;
    @NotNull
    @ApiModelProperty(example="88888.888")
    private Double outputDoubleNum;
    @NotNull
    @ApiModelProperty(example="2018-12-12T11:11:11.111Z")
    private Date outputDate;
}

效果图
模拟请求数据报文：


模拟返回数据报文：

参考链接:

1. swagger 介绍及两种使用方法

https://blog.csdn.net/weixin_37509652/article/details/80094370?utm_medium=distribute.pc_relevant.none-task-blog-baidujs_title-0&spm=1001.2101.3001.4242

2. Swagger介绍及使用

https://www.jianshu.com/p/349e130e40d5

3.SWAGGER 官网

4.【工具使用】API表达工具—swagger

5.Swagger 常用注解使用详解

6.swagger注解详解