spring boot項目從零開始-(3)集成Swagger

簡述

環境

• Idea
• log4j2 + swagger2

最終工程目錄

步驟

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