springboot集成swagger

1、為什麽需要swagger

• 開發人員頻繁的修改服務端的rest接口，而對接人員和測試人員未能在第一時間獲取到最新的文檔
• 接口編寫完成，需要再花一定的時間去按照模板編寫接口文檔費事費力，不如編寫代碼來的輕松

• 如果你也有同感，那麽swagger絕對是你的救星

2、swagger是什麽

• swagger是一個基於註解生成在線api文檔的工具包。有了它編寫好代碼，接口的入參、出參、方法定義上打上指定的註解，輔以描述，那麽框架會根據規範生成格式規範的api在線文檔，與代碼自動保持同步，所見即所得。
• 一個在線的postman,大部分參數為你格式化好了，你只需把形參替換成實參就可以發送請求了
• 支持導出markdown、pdf、word等第三方格式的文檔
• 自動標識最新的api,改動一目了然

3、如何集成

a、引入pom

 <!--swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.7</version>
        </dependency>
 

• 需要說明的是這裏采用的是第三方的swagger-ui，相較於官網的版本，界面更優美，體驗更好。ui只是一個插件，可以無縫替換

b、代碼上增加註解

入參
@Data
@ApiModel("創建流程文檔")
public class AddDocModel extends ToString {
    @ApiModelProperty("文檔的名稱")
    @NotBlank(message = "name不能為空")
    private String name;

    @ApiModelProperty("文件的fileKey")
    @NotBlank(message = "fileKey不能為空")
    private String fileKey;

    @ApiModelProperty("文件id")
    @NotBlank(message = "fileId不能為空")
    private String fileId;

    @ApiModelProperty("是否加密")
    private Integer encryption;
}

出參
@ApiModel("創建文檔的結果集")
@Data
public class AddDocResult extends BaseResult {
    @ApiModelProperty("文檔id")
    private String docId;
}

方法
@Api(tags = "文檔管理", description = "文檔管理")
public class DocServiceImpl implements DocService {
 @ApiOperation(value = "創建文檔", httpMethod = "POST")
    public AddDocResult addDoc(@RequestBody AddDocModel addDocModel) {
        //接口實現
    }
}
 

• 重要註解說明

  ApiModel 用來定義接口的出參和入參的實體類

  ApiModelProperty 定義實體類的屬性值

  Api 用來定義api功能模塊

  ApiOperation 定義一個具體的api

  httpMethod = "POST" 接口只生成POST請求的文檔

  @RequestBody 入參采用json

c、配置swagger

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {
    private final String SWAGGER_SCAN_BASE_PACKAGE = "top.zhuofan.datafly";

    /**
     * 項目裏的靜態資源路徑指向如下
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }


    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title("卓帆網")
                .description("datafly online doc")
                .termsOfServiceUrl("https://www.chenzhuofan.top/")
                .contact(new Contact("", "", "[email protected]"))
                .version("1.0")
                .build();
    }
}

• 配置的主要內容是

  • 將swagger-ui的靜態頁相關的資源添加到springboot可訪問的路徑下
  • 添加swagger的掃描包路徑
  • 添加swagger的版權、開發人員的聯系信息

4、效果展示

5、後續

更多精彩，敬請關註， 程序員導航網 https://chenzhuofan.top

springboot集成swagger