springboot集成swagger2 API文檔 接口方法一目瞭然 參數/返回類型基本數據類型/實體類類型

1 構建springboot項目(自行百度,灰常簡單) 

引入依賴

 <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

 

2新增配置類

package com.wenbin.springboot.springbootswagger2.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration//該註解表示這是一個配置類(其實就是名字上區別於@controller@service@mapper 這些)
@EnableSwagger2// 註解表示開啓swagger
public class Swagger2Api {

    @Bean
    Docket createApi() {
        Docket build = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wenbin.springboot"))// 包掃描的地址
                .paths(PathSelectors.any())
                .build();
        return build;
    }

    @Bean
    ApiInfo getApiInfo() {
        return new ApiInfoBuilder().title("API文檔").description("我的swagger文檔2.0").termsOfServiceUrl("http://xxx.com").version("2.0").build();
    }
}

大致意思很簡單都不多說了

3新增controller

package com.wenbin.springboot.springbootswagger2.controller;

import com.wenbin.springboot.springbootswagger2.pojo.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;


@Api(value = "helloController的api文檔", description = "helloController的api文檔2") // 描述一個類
@RequestMapping("/h")
@RestController
public class HelloController {

    @ApiOperation(value = "hello的入口方法,基本數據類型參數") // 描述一個方法
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    String getHello1(@ApiParam(name = "name", value = "姓名", required = true) @RequestParam(value = "name", required = true) String name) {
        return "Hello springboot!" + name;
    }


    @ApiOperation(value = "這是一個restful方法風格演示")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ApiImplicitParam(name = "id", value = "用戶id", paramType = "path", dataType = "Long", required = true)
    String hello2(@PathVariable(value = "id", required = true) Long id) {
        return "my id is" + id;
    }

    @ApiIgnore// 取消掃描這個方法
    @RequestMapping(value = "/hello3", method = RequestMethod.GET)
    String hello3(@PathVariable(value = "id", required = true) Long id) {
        return "my id is" + id;
    }

    @ApiOperation(value = "這是一個參數爲實體類的演示") //
    @RequestMapping(value = "/hello4", method = RequestMethod.GET)
    Student hello4(@RequestBody(required = false)@ModelAttribute Student student) {
        System.out.println("111 = " + 111);
        return new Student();
    }

}

需要注意一點: swagger註解的屬性, name屬性是表示在swagger中發送請求的參數,value和description纔是類似描述的屬性,和我們javaweb的屬性其實有點相反的.比如 @requestMapping的value纔是 請求的相對路徑,編寫的時候一定要注意哈

這裏要解釋下註解;

@Api(value = "helloController的api文檔",description = "helloController的api文檔2") // 描述一個類
放在類或者接口類上面 description就是描述,會展示在頁面上


@ApiOperation(value = "hello的入口方法,基本數據類型參數") // 描述一個方法
放在方法 或者接口方法上 常用屬性 value

@ApiParam(name = "name", value = "姓名",required = true)
放在參數前面 name屬性是在swagger文檔上運行時傳的值 value是傳的值

@ApiImplicitParam(name = "id",value = "用戶id",paramType = "path",dataType = "Long",required = true)
如果構建的是restFul風格這個要注意需要注意paramType 和 datatype這兩個屬性,填錯的話 項目啓動開始掃描失敗  會報錯實體類

重點標註下實體類相關注解

@ModelAttribute 標註在參數類型爲實體類的上面

@ApiModel(description = "學生",value = "student") 
@ApiModelProperty(name = "id", value = "學生id",dataType = "Long",required = true)

看一下實體類的標註吧(實際上還有一種註解,但是參數爲實體類的方法上都要加就比較繁瑣了,這樣給一個實體類上加上一勞永逸)

package com.wenbin.springboot.springbootswagger2.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "學生",value = "student")
public class Student {

    @ApiModelProperty(name = "id", value = "學生id",dataType = "Long",required = true)
    private Long id;
    @ApiModelProperty(name = "name", value = "學生姓名",required = true)
    private String name;
    @ApiModelProperty(name = "age", value = "年齡")
    private Integer age;

    //省略下getset
}

4啓動,查看文檔樣式

訪問http://localhost:8080//swagger-ui.html

這裏重點截圖下參數爲 實體類的

 

===============