欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

如何优雅的“编写”api接口文档

程序员文章站 2022-03-31 21:18:36
...

前言

  今天我需要把之前写的接口整理成文档,老大给了意见用swagger搞,我像发现新大陆一样的兴奋,迫不及待得去“占有”它。 
  Swagger很容易上手,我花了十几分钟就搞定了。正好接着之前的如何优雅的格式化接口,这里再说一下SpringBoot整合Swagger的简单过程吧

Swagger介绍

  每每get新的技能想分享的时候,按照套路来讲,需要有一个版块将该技能的“前世今生”介绍个遍,但就我接触到完成配置不超过半小时,我觉得让我完完整整的介绍有点太虚了,所以,最好的介绍就是下面的官网 
http://swagger.io/ 
http://swagger.io/irc/ 这个是实时聊天室,刚刚和老外沟通了一番“how are you?fine thk you.and you?” 
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel 这个是一些注解的api 
Swagger有三个模块

  • Swagger Editor
  • Swagger UI
  • Swagger Codegen

      我使用的是Swagger UI,我个人的理解就是“使用Swagger相关的注解并启动服务后,就可以在对应的页面查看API并测试”,先看一下最终的界面 
       
    如何优雅的“编写”api接口文档
    接口描述、参数类型、返回示例在线调试都给你搞定了。你还在犹豫什么,赶快checkou代码,试一试吧

整合

  我接着之前的代码的写(可以在我的GitHub上浏览,或者直接clone到本地再切换到api-norms分支),这里要说一下,使用Springboot整合Swagger贼JB简单,相比较而言,SpringMVC就比较复杂了,这里暂且不谈(以后可能也不会谈了,自从我使用了Springboot之后,就已经开始抛弃SpringMVC了)

maven依赖

老规矩上配置

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

添加Swagger注解

  在Application上直接添加@EnableSwagger2,注意版本,官网上的版本还没有更新到最新的,最新的在Github上看,配置后的代码

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by wangxc on 2017/3/9.
 */
@SpringBootApplication
@EnableSwagger2
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16

可以了,接下来就是描述接口的注解了!在Controller层,做如下配置

package com.quick.api;


import com.quick.po.Address;
import com.quick.utils.BaseResp;
import com.quick.utils.ResultStatus;
import io.swagger.annotations.*;
import org.springframework.util.StringUtils;
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.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * Created with IDEA
 * User: vector
 * Data: 2017/4/12
 * Time: 8:41
 * Description:
 */
@RestController
@RequestMapping("/api")
@Api("springboot整合swagger2") // Swagger UI 对应api的标题描述
public class WebController {

    @ApiOperation("获取地址信息") // 单个接口的描述
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="广东省"),// 每个参数的类型,名称,数据类型,是否校验,描述,默认值(这些在界面上有展示)
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地区",defaultValue="南山区"),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃园路"),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="门牌号",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"), // 响应对应编码的描述
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/address",method = RequestMethod.POST)
    public BaseResp<Address> getAddressInfo(@RequestParam(value = "province")String province,
                                   @RequestParam(value = "area")String area,
                                   @RequestParam(value = "street")String street,
                                   @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        return new BaseResp(ResultStatus.SUCCESS,address);

    }

    @ApiOperation("获取地址信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="广东省"),
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地区",defaultValue="南山区"),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃园路"),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="门牌号",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/address/list",method = RequestMethod.POST)
    public BaseResp<List<Address>> getAddressList(@RequestParam(value = "province")String province,
                                             @RequestParam(value = "area")String area,
                                             @RequestParam(value = "street")String street,
                                             @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        List<Address> lists = new ArrayList<>();
        lists.add(address);
        lists.add(address);
        lists.add(address);
        return new BaseResp(ResultStatus.SUCCESS,lists);

    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78
  • 79
  • 80
  • 81
  • 82
  • 83
  • 84
  • 85
  • 86
  • 87
  • 88
  • 89
  • 90

我只是在原来的基础上添加了下面注解

名称 解释
@Api() 将类标记为一种Swagger资源。
@ApiOperation() 描述针对特定路径的操作或通常是 http 方法。
@ApiImplicitParams 允许多个 ApiImplicitParam 对象列表的包装。
@ApiImplicitParam 表示 api 操作中的单个参数。
@ApiResponses 允许多个 ApiResponse 对象列表的包装。
@ApiResponse 描述操作的可能响应。

更多的看这里

就这么简单,一个基本而又强大的API文档就整理好了!

启动

正常的启动SpringBoot,你会发现控制台输出了这些内容

2017-05-03 21:42:52,975  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
2017-05-03 21:42:52,986  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
  • 1
  • 2

说明Swagger已经成功跑起来了,接下来打开浏览器,输入你链接 
yourdomain/swagger-ui.html 
我的是http://localhost:8080/swagger-ui.html

相信你看了界面并四处点点之后,就会对上面注解的含义有了更进一步的了解~

后记

  这里展示的只是Swagger最基本的功能,更多强大的功能如果后面有运用,我会持续更新的。 
  目前我在看api寻找SwaggerUI输入文件的测试,因为我有个接口需要上传文件,等我搞定,再来分享吧!!! 
  

欢迎进入我的个人博客浏览

相关标签: springBoot swagger