swagger使用

時間 2019-11-19

標籤 swagger 使用简体版

原文原文鏈接

一 swagger簡介

Swagger 是一個用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。能夠跟據業務代碼自動生成相關的api接口文檔html

具備如下好處java

• 及時性 (接口變動後，可以及時準確地通知相關開發人員)

• 規範性 (可以規範表達接口的地址，請求方式，參數及響應格式和錯誤信息)

• 一致性 (接口信息一致，不會出現因開發人員拿到的文檔版本不一致，而出現分歧)

• 可測性 (接口可以測試，以方便理解業務)

二使用方法

1 引入相應jar包（信用分系統使用springboot 1.5.5.RELEAS版本與swagger2.6.1版本適合）spring

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

2建立 swagger 配置類（在 springboot 啓動類 Application.java 同級建立 Swagger2 的配置類 Swagger2 ）後端

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("信用分系統——api文檔")
                .description("讓咱們一塊兒把信用分作好作強大")
                .termsOfServiceUrl("http://wiki.lianjia.com/pages/viewpage.action?pageId=xxxx")
                .version("1.0")
                .build();
    }
}

3 在 controller 和 vo 上使用特定含義註解api

@Api(description = "XX相關接口", tags = {"company"})
@RestController
public class XXController extends BaseController {
    @Resource
    private QueryCreditScoreCompService queryCreditScoreCompService;

    @ApiOperation(value = "查詢分公司列表", notes = "查詢分公司列表")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "loginUserCode", dataType = "string", required = true, value = "登錄人系統號")
    })
    @ApiResponses({
            @ApiResponse(code = 999, message = "後端代碼異常"),
            @ApiResponse(code = 404, message = "請求url路徑錯誤，或者後端服務未部署啓動"),
            @ApiResponse(code = 0, message = "正常返回")
    })
    @RequestMapping(value = "/api/xx/query", method = RequestMethod.GET)
    public JsonResult<List<CompDto>> queryCreditScoreCompList(String loginUserCode) {
        return new JsonResult<>();
    }
}

vo模型上添加返回字段含義springboot

@ApiModel("分公司信息")
@Data
public class CompDto {
    @ApiModelProperty("城市編碼")
    private String cityCode;
    @ApiModelProperty("城市名稱")
    private String compCode;
    @ApiModelProperty("分公司編碼")
    private String cityName;
    @ApiModelProperty("分公司名稱")
    private String compName;
}

訪問部署機器的ip+端口+swagger-ui.html，就能看到接口api頁面微信

三各個註解用法說明：

註解	描述	解釋
@Api	Marks a class as a Swagger resource.	用於類對象，只有在類對象上標註該註解後，相應的api信息才能展現出來.
@ApiOperation	Describes an operation or typically a HTTP method against a specific path.	描述具體的方法
@ApiImplicitParam	Represents a single parameter in an API Operation.	描述具體的請求參數，好比具體的響應方法的參數爲 HttpServletRequest時，我會從該參數中取一些請求參數，則能夠經過該方法單獨定義參數.見下面的具體說明，該參數不能單獨使用，必須和@ApiImplicitParams一塊兒使用，可參考後面的例子
@ApiImplicitParams	A wrapper to allow a list of multiple ApiImplicitParam objects.	組合一組@ApiImplicitParam
@ApiParam	Adds additional meta-data for operation parameters.	定義具體的請求參數，相似@RequestParam 參數，直接在方法參數上使用.
@ApiResponse	Describes a possible response of an operation.	返回值，該類主要有code值與message兩個屬性，code值必須是http 返回code值，默認會有200，404等，不能單獨使用，必須和@ApiResponses一塊兒使用
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.	組合@ApiResponse
@ApiModel	Provides additional information about Swagger models.	提供對請求參數與返回結果中的model的定義