spring boot项目从零开始-(3)集成Swagger

落日映苍穹つ 2023-06-30 06:52 1阅读 0赞

### spring boot项目从零开始-集成Swagger ###

*  简述
 *   *   *  环境
         *  最终工程目录
 *  步骤
 *   *   *  pom.xml
         *  启用
 *  测试
 *   *   *  UserRequestDto.java
         *  TestController.java
         *  结果
 *  备注

# 简述 #

### 环境 ###

*  Idea
 *  log4j2 + swagger2

### 最终工程目录 ###

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70]

# 步骤 #

### pom.xml ###

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

或者

若没有引入fastjson，则引入

<dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>fastjson</artifactId>
                <version>1.2.58</version>
            </dependency>

### 启用 ###

在启动函数加入@EnableSwagger2

@EnableSwagger2
    @SpringBootApplication
    @RestController
    public class MainApplication {

# 测试 #

### UserRequestDto.java ###

package com.ydfind.start.controller.test.model;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    /**
     * 用户请求参数类
     *
     * @author ydfind
     * @date 2020.1.5
     */
    @Data
    @ApiModel("用户类")
    public class UserRequestDto {
    
        @ApiModelProperty(name = "id", value = "用户id", example = "1")
        private int id;
    
        @ApiModelProperty(name = "name", value = "用户名称", example = "张三")
        private String name;
    
        @ApiModelProperty(hidden = true)
        private int age;
    
    }

### TestController.java ###

package com.ydfind.start.controller.test;
    
    import com.alibaba.fastjson.JSON;
    import com.alibaba.fastjson.JSONObject;
    import com.ydfind.start.controller.test.model.UserRequestDto;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.http.MediaType;
    import org.springframework.web.bind.annotation.*;
    
    /**
     * 试验controller
     *
     * @author ydfind
     * @date 2020.1.5
     */
    @RestController
    @Slf4j
    @RequestMapping(value = "/api/v1/test", produces = MediaType.APPLICATION_JSON_VALUE)
    public class TestController {
    
        @GetMapping("/swagger2/1")
        @ApiOperation("swagger2用例：单参数")
        @ApiImplicitParam(name = "param", value = "参数", defaultValue = "默认参数值")
        public String getSwagger1(String param) {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("param", param);
            return jsonObject.toJSONString();
        }
    
        @GetMapping("/swagger2/2")
        @ApiOperation("swagger2用例：多参数")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "id", defaultValue = "1"),
                @ApiImplicitParam(name = "param", value = "参数", defaultValue = "默认参数值")
        })
        public String getSwagger2(int id, String param) {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("id", id);
            jsonObject.put("param", param);
            return jsonObject.toJSONString();
        }
    
        @GetMapping("/swagger2/3")
        @ApiOperation("swagger2用例：单对象参数")
        public String getSwagger3(UserRequestDto requestDto) {
            return JSON.toJSONString(requestDto);
        }
    
        @PostMapping("/swagger2/4")
        @ApiOperation("swagger2用例：单对象参数")
        public String getSwagger4(@RequestBody UserRequestDto requestDto) {
            return JSON.toJSONString(requestDto);
        }
    }

### 结果 ###

访问：http://localhost:8182/swagger-ui.html  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 1]

*  第一个接口测试  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 2]  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 3]
 *  第三个接口如下  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 4]
 *  model  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 5]

# 备注 #

更复杂的，请参考：https://www.cnblogs.com/niunafei/p/11120274.html

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200115201802783.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200115194818868.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200115195004259.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200115195103949.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20200115200033963.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20200115201346269.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NuZGF5WVU=,size_16,color_FFFFFF,t_70