献礼最强API阵营，swagger2Api利器，不可拒绝

比眉伴天荒 2022-12-08 05:44 33阅读 0赞

### ![20210810175737120.gif][] ###

### 一、前言 ###

--------------------

> 经历了几个不同的项目，在前后端分离的过程中，接口文档的重要性不言而喻，
> 
> 但是如何保持一个文档的最新和代码的一致性一直是一个问题，有时候定义了文档，
> 
> 代码中修改了一点小的东西，总会忘记同步修改文档，时间长了，自己都比较蒙，还需要看一下代码才能发现问题。

--------------------

### 二、经历的阶段 ###

> 第一次使用是阿里开源的RAP，但是领导说字段的顺序跟他添加时不一致，他看到对应的文档不好理业务，
> 
> 就直接放弃了这个工具（不知道后面的RAP2有没有这个问题了），然后回归了他熟悉的Word文档的模式，
> 
> 每次入参，说明含义，是否必需的，出参一大批，每次都要这么搞，虽然后期代码的明细很详细，但是耗费的时间还是很长的，
> 
> 毫不夸张的说，40%的时间都是在写文档，最后敏捷开发快速迭代的时候，根本不敢以文档说话了。

--------------------

### 三、新工具的使用-swagger2 ###

3.1、引入对应到jar包

在pom文件中添加swagger2的包，引入相关的依赖，相关的pom文件可以在mvnrepository中搜索相关的包。

<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>

3.2、swagger2的配置文件

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .useDefaultResponseMessages(false)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("利用swagger构建api文档")
                    .description("简单使用swagger2")
                    .version("1.0")
                    .build();
        }
    }

--------------------

### 四、swagger的基础注解介绍 ###

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

*  **@Api：修饰整个类，描述Controller的作用**
 *  **@ApiOperation：描述一个类的一个方法，或者说一个接口**
 *  **@ApiParam：单个参数描述**
 *  **@ApiModel：用对象实体来作为入参**
 *  **@ApiProperty：用对象接实体收参数时，描述对象的一个字段**
 *  **@ApiResponse：HTTP响应其中1个描述**
 *  **@ApiResponses：HTTP响应整体描述**
 *  **@ApiIgnore：使用该注解忽略这个API**
 *  **@ApiError ：发生错误返回的信息**
 *  **@ApiImplicitParam：一个请求参数**
 *  **@ApiImplicitParams： 多个请求参数**

4.1、**@Api修饰整个类，描述Controller的作用**

4.2、**@ApiOperation**

用于描述一个方法或者接口

可以添加的参数形式：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

4.3、**@ApiParam单个参数描述**

@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

4.4、**@ApiImplicitParam 一个请求参数**

@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

@ApiOperation(value = "根据用户名获取用户的信息",notes = "查询数据库中的记录",httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "String",paramType = "query")

4.5、**@ApiImplicitParams 多个请求参数**

参数和@ApiImplicitParam一致，只是这个注解可以添加多个参数而已

@ApiImplicitParams({
                @ApiImplicitParam(name = "nickName",value = "用户的昵称",paramType = "query",dataType = "String",required = true),
                @ApiImplicitParam(name = "id",value = "用户的ID",paramType = "query",dataType = "Integer",required = true)
        })
        public String getUserInfoByNickName(String nickName, Integer id) {
            return "1234";
        }

其余的都类似。

整个controller的代码如下

@RestController
    @RequestMapping("/swagger")
    @Api(value = "swagger2的demo例子")
    public class SwaggerController {
        @RequestMapping("/swagger")
        @ResponseBody
        @ApiOperation(value = "根据用户名获取用户的信息",notes = "查询数据库中的记录",httpMethod = "POST",response = String.class)
        @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "String",paramType = "query")
        public String getUserInfo(String userName) {
            return "1234";
        }
        @RequestMapping(value = "/getuserinfobynickname",method = {RequestMethod.GET,RequestMethod.POST})
        @ResponseBody
        @ApiOperation(value = "根据用户昵称获取用户信息",notes = "查询数据库中的记录")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "nickName",value = "用户的昵称",paramType = "query",dataType = "String",required = true),
                @ApiImplicitParam(name = "id",value = "用户的ID",paramType = "query",dataType = "Integer",required = true)
        })
        public String getUserInfoByNickName(String nickName, Integer id) {
            return "1234";
        }
        @RequestMapping(value = "/getuserinfobyid",method = {RequestMethod.GET,RequestMethod.POST})
        @ResponseBody
        @ApiOperation(value = "根据用户id获取用户信息",notes = "查询数据库中的记录",httpMethod = "POST")
        public String getUserInfoById(@ApiParam(name = "nickName",value = "用户的昵称",required = true,defaultValue = "123-默认值")
                                              String nickName,@ApiParam(name = "id",value = "用户ID",required = true) Integer id) {
            return "1234";
        }
        @RequestMapping(value = "/userregister",method = {RequestMethod.GET,RequestMethod.POST})
        @ResponseBody
        @ApiOperation(value = "register",notes = "注册的实体类")
        public Register userRegister(Register register) {
            return register;
        }
    }

--------------------

**相对应的接口文档如下：**

![cf47fd9e77d676405a13034fe199511c.png][]

**可以直接进行测试**

![1e9818742c92af0b9922609c0531e128.png][]

![dc016625a5cee9e4a3ef4c9166d78e54.png][]

**对应的实体说明：**

@ApiModel(value = "用户注册的实体")
    public class Register {
        @ApiModelProperty(name = "userName",notes = "用户名",dataType = "String",required = true)
        private String userName;
    
        @ApiModelProperty(name = "nickName",notes = "用户昵称",dataType = "String",required = true)
        private String nickName;
    
        @ApiModelProperty(name = "age",notes = "用户年龄",dataType = "int",required = true)
        private int age;
        public String getUserName() {
            return userName;
        }
    
        public void setUserName(String userName) {
            this.userName = userName;
        }
    
        public String getNickName() {
            return nickName;
        }
    
        public void setNickName(String nickName) {
            this.nickName = nickName;
        }
    
        public int getAge() {
            return age;
        }
    
        public void setAge(int age) {
            this.age = age;
        }
        @Override
        public String toString() {
            return "Register{" +
                    "userName='" + userName + '\'' +
                    ", nickName='" + nickName + '\'' +
                    ", age=" + age +
                    '}';
        }
    }

### **五、总结** ###

学习过程就是一个熟悉的过程

--------------------

![20210803154022504.gif][]

![20210626100647986.gif][]

[五年从程序员到架构师！这是我见过史上最好的程序员职业规划][Link 1]

### [(下一篇) ][Link 2][16 条 yyds 的代码规范][16 _ yyds] ###

### [40 个 SpringBoot 常用注解][40 _ SpringBoot] ###

[别慌，在Java面试的时候，面试官会这样问关于框架的问题？][Java]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTcwNjU4_size_16_color_FFFFFF_t_70][]

**想要实时关注更多干货好文，扫描下图关注或微信搜索【**万言尽书上**】关注公众公众号：**

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTcwNjU4_size_16_color_FFFFFF_t_70 1][]

[20210810175737120.gif]: /images/20221123/c5728bd717c046fb963c2c1cd52f635d.png
[cf47fd9e77d676405a13034fe199511c.png]: /images/20221123/0949fbd43ab640f48d2df5b879fcd798.png
[1e9818742c92af0b9922609c0531e128.png]: /images/20221123/89e4ef0a2a914c22bca222d251e045d8.png
[dc016625a5cee9e4a3ef4c9166d78e54.png]: /images/20221123/4a8a66b5670f4b92b52c3c19ebdcd7f4.png
[20210803154022504.gif]: /images/20221123/b2d4128c00314066ae73011cf622d75b.png
[20210626100647986.gif]: /images/20221123/270a0a2063734253b283662a96c04c82.png
[Link 1]: https://blog.csdn.net/qq_41570658/article/details/119028483
[Link 2]: https://blog.csdn.net/qq_41570658/article/details/119147877
[16 _ yyds]: https://blog.csdn.net/qq_41570658/article/details/119146661
[40 _ SpringBoot]: https://blog.csdn.net/qq_41570658/article/details/119147814
[Java]: https://blog.csdn.net/qq_41570658/article/details/119171456
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTcwNjU4_size_16_color_FFFFFF_t_70]: /images/20221123/7ebfa876f6994ea2afad4524773c8046.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTcwNjU4_size_16_color_FFFFFF_t_70 1]: /images/20221123/e0083674dc8b426dae2ef7e7cfdf2327.png