關於swagger文檔的使用方法

引言

最近在後臺開發的時候，使用swagger2進行先後臺接口文檔的聲明。由此碰見的一些問題，寫下來給本身複習。

參考：

https://blog.csdn.net/xupeng874395012/article/details/68946676

 

正文

在進行整合swagger2的時候，首先引入swagger2的jar，因爲我使用的是springboot，因此以springboot爲例。

<!--springboot 集成 swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

引入swagger2的jar包以後，咱們須要配置一個swagger2的配置類，來聲明一些swagger2的配置信息

這樣的話，swagger2就已經配置完畢了。接下來你只須要在你的接口上配置你想要顯示的信息便可。

 

@Configuration  //表示是配置類，要被加載
@EnableSwagger2 //swagger的配置
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation註解的被掃描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("xx", "www.baidu.com", "xxx@126.com");
        return new ApiInfoBuilder()
                .title("cc").contact(contact).description("接口文檔").license("Apache License Version 2.0")
                .version("v1.0").build();
    }
}

接口上信息的配置以下：

@RestController
@Api(value = "user",  tags = "用戶模塊")
@RequestMapping("user")
public class UserController extends BaseController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "用戶添加")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user",value = "用戶" ,required = true,dataType = "String", paramType = "body")
    })
    @RequestMapping(value = "addUser",method = RequestMethod.POST)
    public ResultBean addUser(User user){
        return  resultBean;
    }
}

關於其中@Api和@ApiOperation等的詳細解釋以下：

做用範圍	API	使用位置
對象屬性	@ApiModelProperty	用於出入參數對象的字段上
協議集描述	@Api	用於Controller類上
協議描述	@ApiOperation	用在Controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses裏邊
非對象參數集	@ApiImplicitParams	用在controller的方法上
非對象參數描述	@ApiImplicitParam	用在@ApiImplicitParams的方法裏邊
描述返回對象的意義	@ApiModel	用在返回對象類上

 

關於參數的詳細解釋

屬性	取值	做用
paramType		查詢參數類型
	path	以地址的形式提交數據
	query	直接跟參數完成自動映射賦值
	body	以流的形式提交 僅支持POST
	header	參數在request headers 裏邊提交
	form	以form表單的形式提交 僅支持POST
dataType		參數的數據類型 只做爲標誌說明，並無實際驗證
	Long
	String
name		接收參數名（必須與方法中參數名一致）
value		接收參數的意義描述（描述信息）
required		參數是否必填
	true	必填
	false	非必填
defaultValue		默認值