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

简述

环境

• Idea
• log4j2 + swagger2

代码
https://gitee.com/ydfind/spring_boot_demo/tree/dev-swagger/

目录

步骤

pom.xml

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

或者

<!--
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        -->

若没有引入fastjson，则引入

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

• 第一个接口测试
  
  
• 第三个接口如下
  
• model
  

备注

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