Java | Spring Boot Swagger2 集成REST ful API 生成接口文檔

joyvw 發(fā)布于2019-08-16 10:56 / 3230人閱讀

摘要：集成生成接口文檔原文簡(jiǎn)介由于的特性，用來(lái)開(kāi)發(fā)變得非常容易，并且結(jié)合來(lái)自動(dòng)生成文檔變得方便快捷。使用生成，我們可以得到交互式文檔。聽(tīng)過(guò)與的結(jié)合，生成更加完備的文檔。接下來(lái)將基于與搭建完整的文檔系統(tǒng)。

Spring Boot Swagger2 集成REST ful API 生成接口文檔

原文

簡(jiǎn)介

由于Spring Boot 的特性，用來(lái)開(kāi)發(fā) REST ful 變得非常容易，并且結(jié)合 Swagger 來(lái)自動(dòng)生成 REST ful API 文檔變得方便快捷。

Swagger 是一個(gè)簡(jiǎn)單但功能強(qiáng)大的API表達(dá)工具。幾乎所有的語(yǔ)言都可以找到與之對(duì)應(yīng)的Swagger 版本。使用Swagger生成API，我們可以得到交互式文檔。聽(tīng)過(guò)Spring Boot 與Swagger 的結(jié)合，生成更加完備的REST ful API 文檔。通過(guò)在源碼中添加部分內(nèi)容，系統(tǒng)生成文檔，大大提高工作效率，不用再花費(fèi)大量時(shí)間來(lái)創(chuàng)建文檔，同時(shí)由于同時(shí)是通過(guò)代碼開(kāi)生成文檔，大大降低了維護(hù)成本
Swagger 不僅可以組織生成強(qiáng)大的 REST ful 文檔，同時(shí)也提供了完備的測(cè)試功能，可以直接在文檔頁(yè)面測(cè)試接口功能。

接下來(lái)將基于 Spring Boot 與Swagger 2 搭建完整的API 文檔系統(tǒng)。先來(lái)提前目睹下Swagger 生成的文檔樣式

實(shí)踐 創(chuàng)建Spring Boot 工程

可以參考前文Spring Boot 初體驗(yàn)

在POM 文件中添加 Swagger2 包引用

    
        io.springfox
        springfox-swagger2
        2.7.0
    
    
        io.springfox
        springfox-swagger-ui
        2.7.0
    
    
    //導(dǎo)入測(cè)試需要的庫(kù) 
            
            org.springframework.boot
            spring-boot-starter-data-jpa
        
        
            com.h2database
            h2
            1.4.196
            runtime

本實(shí)例采用的是基于內(nèi)存數(shù)據(jù)庫(kù)H2 的JPA 形式

創(chuàng)建配置類(lèi)

通過(guò)以上方式只能導(dǎo)入 Swagger2 需要的jar包，但當(dāng)前并不能運(yùn)行(雖然Spring boot 支持自動(dòng)化配置)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return  new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.demo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")
                .description("spring boot , swagger2")
                .termsOfServiceUrl("http:github.com/zhuamaodeyu")
                .contact("抓?的?")
                .version("1.0")
                .build();
    }
}

說(shuō)明:

@Configuration: 此注解是告訴 Spring Boot 這是一個(gè)配置類(lèi)，需要在項(xiàng)目啟動(dòng)時(shí)加載該類(lèi)

@EnableSwagger2: Swagger2 是通過(guò)此注解來(lái)啟動(dòng)的

通過(guò) api方法創(chuàng)建 Docket 對(duì)象，其中主要注意 basePackage配置以及私有方法 apiInfo方法創(chuàng)建的基本信息
通過(guò)指定掃描包來(lái)配置，以上配置 Swagger 會(huì)掃描整個(gè)項(xiàng)目工程

創(chuàng)建實(shí)體和respository

@Entity
@Table(name="user")
public class User implements Serializable {
//    @ApiModelProperty(notes = "id")
    @Id

    @GeneratedValue(strategy = GenerationType.AUTO)
    private  String id;
    @ApiModelProperty(notes = "uuid")
    private UUID uuid;
    @ApiModelProperty(notes = "用戶名稱")
    private  String name;
    private  String password;
    @ApiModelProperty(notes = "用戶地址")
    private  String address;
    @ApiModelProperty(notes = "年齡")
    private  int age;
    @ApiModelProperty(notes = "郵箱地址")
    private  String email;
    @ApiModelProperty(notes = "描述")
    private  String desc;
    
    // getter/ setter 方法

}

@Repository
public interface UserRepository extends  CrudRepository {

}

測(cè)試controller

@RestController
@Api(value = "product 商品操作API")
@RequestMapping("/product")
public class IndexController {

    /**
     * 1. 獲取列表
     * 2. 顯示單個(gè)的信息
     * 3. 添加
     * 4. 更新
     * 5. 刪除
     */

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/")
    @ApiOperation(value = "首頁(yè)",notes = "測(cè)試代碼")
    public  String index()
    {
        return  "index";
    }



    @GetMapping("/list")
    @ApiOperation(value = "獲取全部數(shù)據(jù)列表", notes = "獲取數(shù)據(jù)列表")
    public Iterable list(Model model)
    {
        return  userRepository.findAll();
    }

    @GetMapping("/get_user_message")
    @ApiOperation(value = "獲取用戶詳情信息")
    @ApiImplicitParam(name = "userId",value = "用戶ID",defaultValue = "",required = true,dataType = "String")
    public User getUserMessage(String userId)
    {
        return  userRepository.findOne(userId);
    }


    @PostMapping("/save")
    @ApiOperation(value = "保存用戶數(shù)據(jù)")
    @ApiImplicitParam(name = "user", value = "用戶對(duì)象",required = true, dataTypeClass = User.class)
    public String save(@RequestBody User user)
    {
        if (user == null)
        {
            return  "false";
        }

        userRepository.save(user);
        return  "true";
    }

    @PutMapping("/update/{userId}")
    @ApiOperation(value = "更新用戶數(shù)據(jù)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用戶的ID", required = true, dataTypeClass = String.class),
            @ApiImplicitParam(name = "user", value = "用戶對(duì)象", required = true, dataTypeClass = User.class)
    })

    public ResponseEntity updateUserMessage(@PathVariable String userId, @RequestBody User user)
    {
        User user1 = userRepository.findOne(userId);
        user1.setAddress(user.getAddress());


        userRepository.save(user1);
        return  new ResponseEntity("更新數(shù)據(jù)成功", HttpStatus.OK);
    }

    @DeleteMapping("/delete/{userId}")
    @ApiOperation(value = "根據(jù)用戶ID 刪除用戶數(shù)據(jù)")
    @ApiImplicitParam(name = "刪除用戶數(shù)據(jù)",value = "",required = true, dataType = "String")
    public  ResponseEntity deleteUser(@PathVariable String userId)
    {
        userRepository.delete(userId);
        return new ResponseEntity("刪除用戶數(shù)據(jù)", HttpStatus.OK);
    }
}

測(cè)試

實(shí)現(xiàn)以上代碼，啟動(dòng)項(xiàng)目直接訪問(wèn)http://localhost:8080/swagger-ui.html
就能看到Swagger2 所生成的文檔?？梢圆僮髅總€(gè)請(qǐng)求，其下面是具體的描述和文檔內(nèi)容

接口調(diào)試

Swagger 集成測(cè)試
前文提到 Swagger 也提供了接口調(diào)試功能，可以直接根據(jù)接口要求在圖中標(biāo)記處填寫(xiě)接口參數(shù)

Postman 測(cè)試
通過(guò)以上方式可以得到接口文檔，其包含了具體的內(nèi)容，有了這些內(nèi)容，就可以通過(guò)Postman 等專(zhuān)業(yè)的接口測(cè)試工具來(lái)進(jìn)行接口的測(cè)試

Swagger2 常用配置詳解

@Api

@Api(value="onlinestore", description="當(dāng)前控制器中的API 的描述信息")

@ApiOperation

此注解是對(duì)當(dāng)前 API 接口的描述，主要是名稱，詳細(xì)描述，返回值類(lèi)型等信息

@ApiOperation(value = "首頁(yè)",notes = "測(cè)試代碼", tags = {"測(cè)試服務(wù)是否正常"}, response = String.class)

value : API 的名稱

notes : API 詳細(xì)描述信息

response : 返回值類(lèi)型

tags : 默認(rèn)的是以類(lèi)名為標(biāo)簽的，此處可以自定義標(biāo)簽

@ApiResponses

@ApiResponse

此注解是對(duì)API 返回的結(jié)果進(jìn)行描述

   @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successfully"),
        @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
        @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
        @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
}
)

@ApiImplicitParams

@ApiImplicitParam

這兩個(gè)注解是對(duì)API 請(qǐng)求參數(shù)的描述

@ApiImplicitParams({
        @ApiImplicitParam(name = "userId", value = "用戶的ID", required = true, dataTypeClass = String.class),
        @ApiImplicitParam(name = "user", value = "用戶對(duì)象", required = true, dataTypeClass = User.class)
})

@ApiModelProperty
實(shí)體類(lèi)屬性添加描述信息，在接口文檔中可針對(duì)類(lèi)屬性具體含義進(jìn)行查看

@GeneratedValue(strategy = GenerationType.AUTO)
private  String id;
@ApiModelProperty(notes = "uuid")
private UUID uuid;
@ApiModelProperty(notes = "用戶名稱")
private  String name;
private  String password;
@ApiModelProperty(notes = "用戶地址")
private  String address;
@ApiModelProperty(notes = "年齡")
private  int age;
@ApiModelProperty(notes = "郵箱地址")
private  String email;
@ApiModelProperty(notes = "描述")
private  String desc;

通過(guò)以上配置，可以文檔中進(jìn)行查看

擴(kuò)展知識(shí) Mock 系統(tǒng)

在現(xiàn)如今的開(kāi)發(fā)中，一個(gè)由于項(xiàng)目需求緊，開(kāi)發(fā)周期短，通常涉及到后端以及前端協(xié)同工作；一個(gè)由于現(xiàn)在大多采用的是前后端分離的開(kāi)發(fā)形式，前后端交互只是通過(guò) REST ful 接口形式來(lái)實(shí)現(xiàn)的，前后端各自分工工作，所以就存在一個(gè)現(xiàn)象就是前端做的快，后端無(wú)法及時(shí)的給出接口實(shí)現(xiàn)并且開(kāi)發(fā)階段沒(méi)有數(shù)據(jù)支撐而造成前端必須等待后端。

現(xiàn)在可以通過(guò)先定義接口文檔，生成 Mock 數(shù)據(jù)的形式來(lái)進(jìn)行前后端分離開(kāi)發(fā)。前端通過(guò)調(diào)用定義的 Mock 數(shù)據(jù)來(lái)進(jìn)行前端調(diào)試和開(kāi)發(fā)。不需要等待后端的數(shù)據(jù)

接下來(lái)將通過(guò)集成 easy-Mock 系統(tǒng)來(lái)實(shí)現(xiàn)協(xié)同開(kāi)發(fā)

easy Mock

easy-mock 是大搜車(chē)公司開(kāi)源的一套 mock 工具，是一個(gè)可視化，并且能快速生成模擬數(shù)據(jù) 的持久化服務(wù). 下面將 easy-mock 與 Swagger 結(jié)合進(jìn)行協(xié)同工作

搭建easy-mock

下載源碼
easy-mock是一套開(kāi)源系統(tǒng)，其托管在 github 上,可以通過(guò)一下方式獲取源碼
git clone https://github.com/easy-mock/easy-mock.git

修改配置
easy-mock 是使用MongoDB數(shù)據(jù)的，所以需要配置數(shù)據(jù)庫(kù)
進(jìn)入 config文件夾，修改 default.json文件

{
      "port": 7300,
      "pageSize": 30,
      "routerPrefix": {
        "mock": "/mock",
        "api": "/api"
      },
      "db": "mongodb://192.168.99.100:32773/easy-mock_",
      "unsplashClientId": "",

修改 db 添加一個(gè)可以用的數(shù)據(jù)庫(kù)

啟動(dòng)
npm run dev
默認(rèn)的監(jiān)聽(tīng) 7300 端口，可以通過(guò)localhost:7300訪問(wèn)系統(tǒng)

導(dǎo)入 Swagger
進(jìn)入系統(tǒng)創(chuàng)建項(xiàng)目并根據(jù)以下方式導(dǎo)入 Swagger

獲取 Swagger 地址

easy-mock創(chuàng)建項(xiàng)目

通過(guò)

參考

Easy-Mock

SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2

Setting Up Swagger 2 with a Spring REST API

云服務(wù)器 GPU云服務(wù)器生成API文檔 azure java rest api 接口文檔生成工具 Spring Boot

文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/70753.html

發(fā)表評(píng)論

登陸后可評(píng)論

0條評(píng)論

joyvw

男|高級(jí)講師

我要關(guān)注我要私信

TA的文章

tensorflow2.0安裝

閱讀 3127·2023-04-25 15:02
手把手教你實(shí)現(xiàn)Android真機(jī)遠(yuǎn)程截屏

閱讀 2835·2021-11-23 09:51
寶塔面板docker安裝next-freenom – 為freenom免費(fèi)域名自

閱讀 2045·2021-09-27 13:47
免費(fèi)申請(qǐng)Microsoft 365云端辦公套件對(duì)比本地Office軟件區(qū)別

閱讀 2003·2021-09-13 10:33
前端面試題大集合：來(lái)自真實(shí)大廠的532道面試題(只有題，沒(méi)有答案)

閱讀 986·2019-08-30 15:54
錯(cuò)誤，刪除

閱讀 2651·2019-08-30 15:53
Bootstrap3.x - 源代碼分析

閱讀 2868·2019-08-29 13:58
CSS: hover選擇器的使用

閱讀 901·2019-08-29 13:54

成人国产在线小视频_日韩寡妇人妻调教在线播放_色成人www永久在线观看_2018国产精品久久_亚洲欧美高清在线30p_亚洲少妇综合一区_黄色在线播放国产_亚洲另类技巧小说校园_国产主播xx日韩_a级毛片在线免费

資訊專(zhuān)欄INFORMATION COLUMN

上云采購(gòu)季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來(lái)選購(gòu)！

Java | Spring Boot Swagger2 集成REST ful API 生成接口文檔

接口調(diào)試

easy Mock

相關(guān)文章

**《 Kotlin + Spring Boot ：下一代 Java 服務(wù)端開(kāi)發(fā) 》**

***SpringBoot* 實(shí)戰(zhàn) (五) | 集成 Swagger2 構(gòu)建強(qiáng)大的 RESTful *API***

SpringBoot 2.X Kotlin與Swagger2生成API文檔

發(fā)表評(píng)論

0條評(píng)論

joyvw

男|高級(jí)講師

TA的文章

tensorflow2.0安裝

手把手教你實(shí)現(xiàn)Android真機(jī)遠(yuǎn)程截屏

寶塔面板docker安裝next-freenom – 為freenom免費(fèi)域名自

免費(fèi)申請(qǐng)Microsoft 365云端辦公套件對(duì)比本地Office軟件區(qū)別

前端面試題大集合：來(lái)自真實(shí)大廠的532道面試題(只有題，沒(méi)有答案)

錯(cuò)誤，刪除

Bootstrap3.x - 源代碼分析

CSS: hover選擇器的使用

最新活動(dòng)

資訊專(zhuān)欄INFORMATION COLUMN

上云采購(gòu)季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來(lái)選購(gòu)！

Java | Spring Boot Swagger2 集成REST ful API 生成接口文檔

接口調(diào)試

easy Mock

相關(guān)文章

發(fā)表評(píng)論

0條評(píng)論

男|高級(jí)講師

TA的文章

最新活動(dòng)

上云采購(gòu)季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長(zhǎng)期優(yōu)惠，快來(lái)選購(gòu)！